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VIEWPOINT 


By Bill von Hagen 


Fok Cross-Ptatform Standards, the Mac 
ls as Standard as Anybody 

This issue's viewpoint Ls what some might consider heresy — 
discussing die importance of seeing die Mac an equal partner in 
“standards" ! don’t mean this just in tenns of this weeks hot 
buzzphrase (“Open Source ", anyone?), but rather in terms of time 
tested buzzwords such as XML, Java, EDI. and eBusiness. 

At IlnsL glanc e, it’s <xkl to see a Macintosh piece whose fcxus Ls 
interoperability and platfonn-inclependence. Tfie reason Lhai this is 
odd is that, as Mac lovers, we're often used to thinking of ourselves 
as the voice c rying out in the wilderness, some sort of hi-tech Mr. 
Smith in “Mr Smith Goes To Washington," We do lids to ourselves by 
our endless (and justified! — ix >ps) tnimpeting of the Mac as the < >ne 
true platform, but let s face it — tliat attitude just doesn’t cut it in the 
business world tcxiay. To me, the Mac slill lias clear advantages for 
most gnipities and artistic work, but (to paraphrase) ‘the business of 
America today is eBusiness; We can design all the web sites, 
graphics, and other media we want using Macs, but if we want to 
make the Mac into more than just a niche player we've got to use it 
for business and business development — not just for software 
development to feed die needs of a few million Mae-loving intimates 
and the occasional c onvert or new initiates. 

The good news is dial you can already do tills. The tools are 
already here. You can start now. Today’s web environment and die: 
cross-platform thinking it fosters already makes the Mac a viable 
player. We just have to respin our story a little bit. 

To recap the world of eBusiness today in a paragraph or two, 
Java is a object-oriented language dial is compiled so tliat it can run 
on any platform with a Java virtual machine. Virtual machines are 
freely available for almost all hardware platforms, from mainframes 
(IBM VM), to workstations (almcxst all flavors of UNIX), to }K i rsonaJ 
computers (Macs, Windows 95, 98, and NT), and even hand-helds 
(Psion organizers), All of these can run the same platform- 
independent Java applications, even using a GUI thanks to portable 
Java GUI libraries such as Swing. 

Just as Java is a platform-independent independent way or 
writing applications, XML is a software-independent way of 
exchanging data, XML is a markup language tliat lets you define 
structured ways of organizing data, The most common use of XML 
Ls in defining different types of structured documents and c rediting 
documents that conform to them. Businesses have many different 
tyj>es of data that must conform to a specific structure: spreadsheets, 
databases, and even general purpose corporate information such as 
that exchanged via EDI (Electronic Data Inteixhange) fomiaLs. All of 
these have their own rules for identifying the meaning of different 
portions of llie data that they contain. XML provides a unified 
structure for expressing all of therm. 

Together. Java and XML provide a platfrimvinclependenL, 
software-jnde[X'ndeni vision for the futuiv of a imputing. Anyone 
can play as long ;is they can follow rile standard rules. Macs have 


specific advantages in specific fields, but dam it, we can also lx as 
standard as anybexty. 

Regardless of your age, mind set. and favorite ux>Is, the Mac 
already has everything you need for XML and Java development. 
Integrated Development Environments (IDEs) for developing Java 
applications on the Mac are readily available from vendors such as 
Metrowerks, Symantec, Smith Resources, and many others. There’s a 
fair amount of Mac XML development software already out there for 
die Mac. including the HexMac PublLshing Tcx>ls, the Emile 
extensible markup editor, XpublLsh, bhedit, and many more. 

There are also plenty of uxjIs for people like me. Call me a 
Luddite if you will, but since the early eighties, I’ve written docs and 
code in the same tool —a text editor. 1 love markup languages such 
as XML because 1 can still use my favorite editor and pnxjuce 
fxifealy formed tfocuments. I can write axle in another window ai 
tiie same time. But enougli about me — the point is that the tools 
arc out there, regardless of what you like to use. The skills are out 
ihere - a million Mac applications show that we have them. The 
opportunity Lsom there. 

'litis isn’t suggesting that we stop developing Mac-specific 
applications. To quote Vladamir Nabakovs Lolita, "Please, don't 
slop!” The Mac GUI is a wonder of Ixxmty and usability. (Though I 
will never lx; able to explain or defend the QuickTime 4 GUI!) There 
will always lx.* a place for Mac-only applications that lake advantage 
of the Mac OS. Ed frankly expert more of ihese sorts of applications 
once Mac OS X is available. 

We’rv not “dumbing down" the Mac, we’re wising up ourselves 
and the business community by nothing more than putting a .slightly 
lieuer spin on the kinds of development you can already do on the 
Mac. Which is platform-specific things, and standard things. And we 
can play in the platform-independent, software-independent 
sandlx)x as well as anylxxJy, 

eBusiness, XML, and Java could lx* the hest things tliat ever 
happened to the Mac since PageMaker at the dawn of Lime. ( which 
was April, 1984) Some might say that those aren't Macintosh 
applications or environments per sc. I hie the smart ones among us 
will lx- quick to yell "And that's the whole [xirntT I hey re as much 
Mac applications and environment as they aie Windows or UNIX 
ones (Spin, spin.) Let’s get eBusy. 

URLs 

Java IDEs: 

Metrowerks http://www.metrowerks.com/java 
Symantec http://www.symantec.com/vcafemacpde/index.html 
Smith Resources http://www.smithresources.net/ 

XML Development: 

HexMac Publishing Tools http://www.hexmac.com 
Emile http^/www.fn-progress.cQm/emile/ 

Xpublish http://interactionan-progress.com/xpublish/mdex 
RREdit http://www,barebones,com ®ti 
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software security key or a getting in anyone's way. Call now 

sales tool? to request a Developer’s Kit and 
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advantage. USA: 1-800-223-4277 
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license multiple software modules 072-3-6362 222 

and applications. You can instantly 

unlock or upgrade them in the WWW.aks.COITl/mt 

field. Plus you can freely distribute — - ,, 

demos A] Ann [SJ 

Bottom line: MacHASP USB locks /\ L-Zvl--' L/ I L Tl 
out illegal users and unlocks your knowledge SYSTEMS LTD 

Mac software protection provider, Micro Macro Technologies, becomes part 
of Aladdin, giving its customers even better service from the number one name. 
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GETTING 

STARTED 


By Dan Parks Sydow 


Catching Up With Carbon 


The current state of the 
Carbon API 


Back in January of this year we looked 
at Apple’s then-new Carbon — the 
application programming interface (API) 
meant to Ire a replacement for the 
Macintosh Toolbox, At that time we said that 
Cartx>n existed so that a programmer could 
write an application that would run on 
either a Mac hosting Mac OS 8 or on a Mac 
hosting the upcoming Mac OS X, That's still 
true. But now, with the release of Mac OS 9 
from Apple and die release of support files 
from Metrowerks, a programmer can move 
from theory to application. Carbon isn't 
completely finalized, but the bulk of it is in 
place. So now you can start writing and 
compiling code to verify that your program 
is indeed Carbon compliant. 

About Mac OS X and Carbon 

If you aren’t at all familiar with Mac 
OS X or with Carbon, and you have access 
to the Getting Started article in the January 
1999 issue of MacTech, go ahead and give 
it a read. If you don’t have that article, or 
just want a very quick summary of these 
two Apple software technologies, make 
sure to read this section. 

Mac OS X is the soon to-be-released 
version of the Mac operating system that is 
to bring on important and necessary 
enhancements Lhat both programmers and 
users have been wailing for. Chief among 
thexse improvements arc increased stability 
(via a protected address space for each 
process, or running application), increased 
responsiveness (by way of preemptive 
multitasking so that the processor can 


better serve each process), and dynamic resource allocation (via 
a “use-as-needed” scheme where a process uses system 
resources such as memory only as needed). Mac OS X has three 
separate application areas, or environments: 

Classic This area, formerly called die Blue Box, allows for 
the running of any Mac OS 8 application. If a program runs on 
Mac OS 8 now, then a software developer need make no changes 
to an existing program in order for it Lo nrn on Mac OS X. There 
is a key drawback to leaving Mac GS 8-compatible applications 
untouched, however While such a program runs fine on a Mac 
hosting Mac OS X, it won t take advantage of the new features of 
Mac OS X (as mentioned in the above paragraph). 

Carbon Tills area allows for the running of Mat: OS 8- 
compatible applications that have been recompiled, or fine-tuned, 
for Mac OS X. Such a program does take advantage of the new 
features of Mac OS X. Such a program can also be am on Mac OS 
8, though of course when ii does it won't retain Mac OS X 
features such a.s enhanced performance (since the benefits of Mac 
OS X of course won't be present on the Mac: OS 8 Macintosh). 

Cocoa This environment, formerly referred to as Yellow 
Box, is for new programs dial, like Carbon applications, take- 
advantage of the new features of Mac OS X. A Cocoa application, 
however, won't run on a Mac hasting Mac OS 8 or 9. 

The difference between a Classic application and either a 
Carbon or a Cocoa application arc obvious — a classic 
application isn't upgraded to capitalize on the benefits of Mac OS 
X. The difference between a Carbon application and a Cocoa 
application aren’t so obvious. To an end user the differences 
aren't noticeable at all. That’s because the differences are found 
in the source code used to create both types of program, A 
Carbon application is built from code that uses the Carbon API 
— the modified Toolbox API. A Cocoa application is instead built 
from an entirely different API — one based on the NeXT 
OpenSLep API. While a Carbon application is typically written in 
C or C++ (or possibly Java), a Cocoa application is typically 
written in Java or Objective-C. Because this column has for years 
featured the Macintosh Toolbox API (the only API there was for 
creating Mac programs sporting the Macintosh graphical user 
interface) > well l>u focusing on Carbon. That way almost 
everything you’ve learned in previous Getting Started articles still 
applies to your future Carbon programming endeavors. More 
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advanced programmers, or programmers familiar with NeXT's 
OpenStep API would be wise to learn Cocoa — it's tools 
(primarily Interface Builder, which let’s you "draw” your 
applications user interface and add common functionality 
lx:forc you start writing code) aid in the rapid development of 
Mac OS X applications. 

Converting to Carbon 

Apple's goal in developing the Carbon API: to give 
programmers an easy means to make their existing applications 
ready for Mac 05 X. By starting with the time-tested, and very 
familiar, Macintosh Toolbox, Apple knew that a programmer’s 
learning curve would be minimized. When you look at the 
routines that make up the Carbon API you will notice that they 
look pretty much like the routines that make up the Macintosh 
Toolbox API Carbon, it turns out, is simply a deaned-up and 
enhanced Macintosh Toolbox. That’s great news for those of us 
familiar with the Toolbox. 

The Macintosh application model (event-driven, menu and 
window interface) is essentially unchanged in Carbon. Mac OS 
8 (and now Mac OS 9) and Mac OS X are built on different cores, 
though, so how an application accesses system services does 
differ in some respects. To write an application using Carbon, or 
to Carbon-tune an existing application, there are a few issues 
you need to be aware of 

Separate Application Address Spaces 

A chief advantage of Mac OS X is that each application runs 
in it’s own protected address space. When one application 
crashes, other running applications remain unaffected. A Carbon 
application takes advantage of Mac OS X features, so a Carbon 
application runs in its own protected address space. If your 
application uses system memory or temporary memory, you’ll 
need to make some changes. Simple applications, like the ones 
we’ve been writing here in Getting Started articles, don’t take 
any liberties with memory, so this issue won’t affect our (and 
perhaps, your) trivial programs. 

If you're writing more complex applications, check your 
source code for use of the FreeMem(), PurgeMem(), and MaxMemQ 
Toolbox functions. These routines are supported in Carbon, and 
will deliver expected results when your Carbonized program runs 
under Mac OS 8. But when that same program runs under Mac 
OS X, these routines do essentially nothing. You’ll want to 
evaluate their use in your application to see if the tasks they are 
expected to accomplish are important under Mat: OS X 

68K Code and the Mixed Mode Manager 

When Apple made the transition from 68K to PowerPC 
processors, the concept of the universal procedure pointer 
(UPP) came about. A UPP is a pointer to a data structure that 
holds information about a function. One of the pieces of 
information specifies the instruction set architecture of the 
function. That is, whether the function can be handled directly 
by the PowerPC processor or whether the Mixed Mode Manager 
must pass Instructions to a 68K emulator for preliminary 
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processing. Mac OS X does not run 68K code, so the Mixed 
Mode Manager is of no use U> an application running under Mac 
OS X. If your application includes Lhe use of the Mixed Mode 
Manager, though, you shouldn't need to worry. Carbon supports 
IFPPs transparently (meaning that you can still use tTPPs so that 
your application runs properly on Mac OS 8). 


to compile the above code using the Carbon API will result in 
errors. Thai's because Carbon won’t let you access the opaque 
fields of the WindowRecord. Instead of using a WindowPeek. 
you'll use the new SetWindowKindO function: 

theWindw ” GetNevWindow( 128 , nil, (VindowPtr) - ll< )i 
SetWind,CfvKind{ theWindow, kDra win ^Window ): 


Printing 

If you application includes the ability to print, then you'll 
need to make changes to it — Carlxm includes a new Priming 
Manager. By using live new Printing Manager your application 
will be able to print on Mac OS 8 using existing primer drivers 
and be able to print on Mac OS X using new printer drivers. 
Detailed coverage of the new Carbon Printing Manager is well 
Ixyond she scope of this article but you can take a peek at 
this managers functions and data types by looking at the header 
file PMAppfication.b 

Callback functions 

A callback mutine is an application-defined function that 
the system executes when some task is completed. Back in this 
year’s March Getting Started article we provided an example of 
a callback routine — we wrote one that the Sound Manager 
invoked to let our program know that a sound had completed 
playing. Carbon supports such application-defined callback 
routines, so the callback code of an application (such as our 
March example AsynchPlayer) will not need modification. 

Carbon and Opaque Data Structures 

Much of the Carlxm API consists of Toolbox routines that 
have been made Mac: OS X compatible. But Carbon also includes 
new routines as well. A big change brought on by Carbon is that 
many commonly used data structures are now opaque. That is, 
their internal structure — the fields or members that make up 
the structures — are hidden from the programmer. For instance, 
while a window still consists of a WindowRecord, your 
application should not attempt to directly access the fields of 
that record. The same holds true for dialog boxes, menus, 
controls, and the QuickDraw globals. 

To allow your program to access opaque data, Carlxm 
introduces new accessor functions. Here's an example. In the 
past, you could directly access a WindowRecord field by first 
casting a WindowPtr to a WindowPeek. and by then examining a 
field of the WindowRecord If your program defined a few 
different types of windows, you could keep track of what type 
a window was by storing an application-defined constant in lhe 
windowKincf field of the window’s WindowRecord. Like this: 

^define ktlravhigWiudow l 
^define kToxtWindow 2 
WindowPt r thyWindow: 

theWindow - GetNewWindow{ 128, nil, (WindowPtr)- II. ): 
(WindowPeek) theWindow >windowKind = ktkawingWinduw; 


Carbon introduces a nurnljer of new routines to make life 
with opaque data structures manageable. You'll be .seeing a lot 
more of them in fuLure articles. 

CodeWarrior and Carbon 

Compiling your Carbon code and building an application 
results in an executable (a program) that can run on Mac OS 8 
or 9, and can run on Mac OS X, You don’t need to keep two 
separate sets of code, or build two applications. If you’re 
fortunate enough to have a Mac running Mac OS X. you can do 
your work on that machine. If you have Mac OS 8 or 9, you on 
now also lake care of business. This wasn’t possible a while 
back because die Ux>ls for non-Mac OS X development didn’t 
exist for Mac OS 8. Now they do if you have a recent version 
of Metrowerks Code Warrior, such as Code Warrior 5.O.. 

Carbonljh Shared Library 

To build a Carbon application you'll create a new CodeWarrior 
project based on Code Warrior's Carlxm stationary. Doing dial 
results in a project that Includes a Carbon Support folder which 
holds a number of files dial may he unfamiliar to you. Figure 1 
shows die project that results from the Carbon stationary. Note that 
it you're using an older version of CodeWarrior, you won't have the 
Carbon Support folder in your Metrowerks CodeWarrior folder. 
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Figure 1. A CodeWarrior project based on Carbon stationary. 


The above snippet creates a new window and specifies that 
this window lie considered to be a drawing window. Attempting 


Of key interest here is the CarbonLib and LiteCarbonLib shared 
library files, lhe Cartx>nUb shared library provides die Carlxm 
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functions that your project will be using. LiteCarbonLib holds a 
subset of the functions found in CarbonLib. Mac OS 8 does support 
all of the existing Caibon functions. As of this writing, Mac OS X 
doesn'tt include support for all of the Carbon functions, 
LiteCarbonLib holds only those functions currently supported by 
Mac OS X. If you want to build an application that is Carton- 
compliant, and you don't need to test it under Mac OS X now, 
then your interested in CarbonLib. If you need to lest your Carton- 
compliant application on Mac OS X now, you'll want to build it 
with LiteCarbonLib to ensure that it will nin on Mac OS X now. 
Once Mac OS X fully supports all the Carbon functions 
(remember, Mae OS X Client version for consumers isn’t shipping 
as of this writing), this dual-library issue will disappear — well all 
only need the full set of functions found in CarbonLib. 

Project Targets 

Tile project target menu near the top left of the project 
window is used to determine what type, or types, of applications 
get built when you choose Run or Make from the Project 
menu. For Mac projects you've typically selected a 68K. 
PowerPC, or fat application. As shown in Figure 2 r here in a 
Carton project, you'll select a Mach-o, CarbonLib, or 
LiteCarbonLib application (or ail of those types), Here's how 
you’ll decide which target to select. 

Carbon Lib When you perform a build on a project (when 
you di(X)se Run or Make from the Project menu), CbdeWarrior 
creates an object file from each source file and then links these 
separate object files (along with the resources in project resource 
files) to form a single executable, or application. For Mat' OS 8 
application development, the resulting object files are in Cede 
Fragment Manager (CFM) format. These code fragments are 
stored in Preferred Executable Format (PEF) containers and are 
managed by the Code Fragment Manager. Code Warrior pretty 
much hides those details from you — so don'L feel bad if 
acronyms such as CFM and PEF are new to you. Mac OS X 
supports the Code Fragment Manager, so tills way of creating an 
application that runs on Mac OS X still works. In fact, if you're 
creating a Carton application that is to be able to run on both 
Mac OS X and on Mac OS 8, you must create an application 
using CFM object files (otherwise the resulting application 
couldn't run on Mac OS 8). To tell Code Warrior to generate a 
Carbon application that runs on both Mac OS 8 and Mac OS X T 
you'll choose the CarbonLib item from the project window's 
target pop-up menu. That's what's being selected in Figure 2 
(there the menu item is named Basic A pp CarbonLib because the 
CarbonLib item is prefaced with the project's name). 

UteCarfoonlib If you're toilding the application on a Mac 
running Mat' OS 8, and you may to soon testing the application on 
a machine running Mac OS X, you may want to instead use the 
UicCarbonLib menu item (the last item in the menu shown in Figuie 
2), Recall that Mac OS X doesn't support all Carton routines at this 
time, so treating a LiteCaibonUb application ensures that when you 
mn die resulting application on Mac OS X it won't attempt to access 
unsupported routines. When Mac OS X fully supports Carbon, 
there'll be no need to build a LiteCartonLib application. 
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Mach-o Mac OS X supports CFM object files and the Code 
Fragment Manager, and thus Carbonlib applications. But it also 
supports the Mach object file format, also referred to as Mach-a Mac 
OS 8 doesn't support Mach-o, so you can only target Macho if your 
application is only meant to run on Mac OS X. A more likely reason 
lo target Mach-o is for debugging purposes. At this time Mach-o is 
the best format for debugging an application on Mac OS X. 

BuildAinypes Hopefully this target Lype is self-explanatory — 
choosing it results in the building of all three types of executables. 



Figure 2. Mac OS XZCarhan targets in CodeWarrior. 


Source Code 

If your application is a simple one, as many of our Getting 
Started examples are, you may be able to make its code Carbon- 
compadble very easily. In fact, just a few alterations to your code 
may do the trick. One addition you will need to make is the 
following line of code to the lop (before any ^includes) of one 
of your source files: 

^define TARGETJCARBON 1 

The TARGET_CARBGN conditional is used to specify that 
any included header files should allow only Carbon-compatible 
functions and data structures. Since much of the original 
Toolbox is Carbon-compatible, many of the functions and data 
structures in a universal header file will in fact be Carbon- 
compatible. But some of die code won’t be, or some differences 
between new Carbon code and older Toolbox code will be 
present. The TARGET. CARBON conditional makes it possible 
for Apple to keep a single set of universal interface header files. 
If you took through the over one hundred files that make up the 
latest set of universal interface files you’ll find instances where 
die TARGET.CARBON conditional appears: 

flit TAKGET.CARBON 

// (jrixjri-spcdlii: stuff 
If end if /*TARGET_CARBON *f 

Other changes you need to make to your source code 
are dependent on just what your program does, in this article 
weVe provided a few instances where you'll need to watch 
for Carbon-compatibility, 

Testing For Carbon Comfatuiiijty 

Back in January we discussed how you can easily test your 


code for Carbon compatibility. The steps for doing so remain 
essentially the same — you’ll Carbon Date your code using 
Apple's Carbon Dater. A free download of this software program 
is available from Apple at <http;//developcr,applexom/maco5x/daterhtml>. 

To use die Carbon Dater software you simply drag and drop 

_your program (not the source code, but rather the ready-to-run 

standalone application itself) onto the Carton Dater application 
icon. Carbon Dater will launch, examine the application that was 
dropped on it, and generate an output file. This output file needs 
further analysis. Apple does that free, quickly (usually in less 
than an hour), and by an automated process if you e-mail die 
Carbon Dater output file (which ends with the extension .COT) 
to CarbonDating@apple.com (note that Apple recommends that 
you send the ,CCT file as a stuffed file). 

In exchange for your submission of a .CCT file, Apple 
sends you a report in HTML format. Open the report in your 
favorite Web browser to see how Carbon-compatible your 
application is* Figure 3 shows a part of that report for a 
small application named BasicApp. 



Figure $ A Carbon report from Apple , 


Apple examines the Carbon Dater output file in order to 
determine all of die Toolbox functions your code accesses, and to 
then tell you which calls you need to update or replace. Every 
objectionable, or questionable, Ttxifbox call your program makes 
appears listed in the report. After looking over the report you’ll 
have an idea of how much work (or how much more work) is 
needed in order to make your application frilly Carbon-compliant. 

Tnj. Next Month... 

Apple is very well along in its job of creating llie Carbon API 
— but die Carbon API is not yet finalized. When that time comes 
(and it will be sixin), we’ll have one more Carbon-related Getting 
Started column. In that article well look back at a previously 
written Getting Started example program, and look forward at 
what it takes to Carbonize it. We h lf provide the complete source 
code listing — with detailed discussion — one just what changes 
are needed to get the program ready for Mac OS X and for Mac 
OS 8 and 9. Until then, well move on to other topics... E 
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Now upgraded with additional features. 


E ach year over $11 billion is stolen from software developers world wide. 1 

The BSA estimates that over 40% of new applications installed 
yearly are pirated. Disk swapping and copying aren’t the only prob¬ 
lems developers need to combat. E-commerce piracy is now surpass¬ 
ing traditional forms of software piracy, raising developer revenue losses 
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To prevent software piracy and track those who attempt it. New Wave Software, Inc. 
has developed SPI™- Software Piracy Intervention. SPI adds a protective layer 
to your program that allows only those end-users who legitimately pur¬ 
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your products and significantly increase your revenue without increasing 
production costs. 
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PROGRAMMING 


By Erick J. Tejkowski 


REALbasic Plugin Programming 


Extend REALbasic to suit 
your needs 


basic custom control. Finally, we will wrap it up by including 
some discussion on the potential uses of REALbasic plugins. 


Introduction 

REALbasic is an object-oriented. 
Basic-flavored, rapid application 
development environment. With it you 
can build and compile Macintosh and 
Windows applications. The environment 
comes complete with numerous classes, 
objects, properties, and methods for the 
programmer to use. Many different 
aspects of Mac/PC programming are 
included in the REALbasic environment, 
for example windows, QuickTime, 
sockets, and threads to name a few. 
Sometimes, however, your application 
requires something that REALbasic cannot 
provide. To gain this functionality, the 
programmer has to tap other resources. 
For example, REALbasic allows the 
inclusion of Applcscripts, HyperCard 
XCMPs, and shared libraries. 
Furthermore, REALbasic can also l>e 
expanded with die use of native plugins. 
In this article, we will examine the 
methods used in developing plugins for 
REALbasic using Metro we rks Code Warrior. 

To begin, we will prepare the 
compiler for REALbasic plugins. Then, 
we are on to coding, in the first code 
example, we will examine some sample 
code for a method-based plugin. The 
second example will look at code for a 


Thf Setup 

A REALbasic plugin is a code resource. It can come in 
68K or PPG flavors, but unless your plugin requires some 
specific speed enhancements or other PPG specific code, 
most people prefer to make 68K versions, as this allows 
everyone to take advantage of the plugin. There are also 
some specific differences between REALbasic I and 2 
versions of plugins. For this article, we will only consider 
REALbasic 2 plugins, as it is the most current release, but 
most of the information will pertain to REALbasic I plugin 
development, although there are some distinct differences. 
Interestingly, some REALbasic? 1 plugins work with REALbasic 
2, but never vice versa. 

Since the plugin is a code resource, GodeWarrior needs 
some special adjustments before we can begin work on our 
first REALbasic plugin. To begin, create a folder named 
MyRBPlugin. To this folder add the file named 
PiuginMain.cpp and ihe Folder entitled Includes. These can 
be found in the REALbasic plugin SDK on REALsoftware's 
web site. See the Bibliography for more information. Next, 
launch Code Warrior and create a new project with the 
MaeOS:C_C++:MacOSToolbox:68K stationery. Uncheck Lhe 
Create Folder check box. Name the project MyPIug.x 
(option-p) and put it in your MyRBPlugin folder. Remove the 
SillyBalls.e, and StllyBaJIs.rsrc files. 

Select New from the File menu and create a new 
document. Save it in your MyRBPlugin folder with the name 
MySource.cpp. Select Add Window from the Project menu, 
which will add MySource.cpp to your project. Select Add 
Files... from the Project menu and add the PiuginMain.cpp file 
you copied to your folder earlier. Your project should 
resemble Figure I. 


Erick J. TejkoWsSki is an IT professional for the Macintosh-loving Zipatoni Company in St. Louis, Missouri, When he's not 
busy trying to raise a trilingual daughter (English,Spanish, and German) with his wife Lisa, he programs shar eware and 
freeware software for his own Purple E Software. HLs software hits appeared in Macintosh publications around the world. You 
can reach him at ejt®THjrcom2000.com. 
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figure /. MylHug li project window. 

Your project target might not look exactly the .same as 
Figure 1. Your target might l>c named Mac OS Toolbox DEBUG 
68 K. instead of plugin68k. To change this, you need to make 
some changes to the preference settings. It jtisi so happens that 
this is also where code resource sellings are made. This leads us 
to our next step. 

Open the Project Settings dialog from the Edit menu. Select 
the Target Settings in the Target submenu. Change die Target Name 
Ln plugm68k. NexL, select the Access Paths item. Select User Paths 
and dick the Add button, Chcx>se the folder entitled Includes that 
you copied to your project folder earlier. Now, select 68K Target 
and name your plugin. Name il myPlugin68K. Make sure that 
Code Resource is selected from the Project popup menu. Change 
the Creator to SfTg, the Type to ltBPl, the ResType to PL68, and 
the ReslD to 128, Figure 2 recaps the 68K Target settings. 



Figure 2 . 68K Target Settings, 

Finally, in the 68K Processor .settings, check die following 
checklxjxes: 68020 Codegen, MPW C Calling Conventions, 
4-Byte lnts T and 8-Byte Doubles, Click the Save button and 
relink the project if necessary. 

Additional Resources 

TTiese setdngs will work for both axle examples Lo he 
discussed later. To build Lite custom control in listing 2 t though, 


one more step is required. A control in REALhasic also needs 
some additional resources. Start your favorite resource editor and 
create a new file named MyKsrc.rsrc, To this file, add a PICT 1 
resource with an ID of 128. T his is the unselected appearance of 
the control on Lhe REALhasic Ltxjlbar, A 'PICT resource wid) an 
ID of 129 is the selected appearance of the control (Le. the 
appearance as the control Ls dragged to a window). Both of these 
resources should have pixel dimensions of 28 wide by 21 high to 
appear properly in the REAlbasic toolbar. In addition to the 
required 'PICT resources, our control is going to make use of 
some icon resources. These icon resources will lx: used Lo draw 
the custom switch we are going to create. 

Add a resource of type icl8 with a high number, to avoid 
collisions witli REALbasic's own resources. For our example use 
1280. This is the appearance of the switch when used in a REALbasic 
application. Draw wliatever you would like here or use the resource 
example available on the MacTech web site. This resource will be 
die “off position. Since we aie using an icon lie re. the dimensions 
are 32 wide by 32 high. Once you iiave completed the artwork for 
your switch, drag die idB 1 to die ICN# 1 and icl4 L boxes on the right. 
You need not worry about the other sizes, as they are not important 
for this example. Since we am building a toggle style switch as our 
custom control, you will also need to add another icon resource. 
Thus resource will lx* the “on rf position, Create it just as you created 
the “off* position, but give it a number of 1290. An example resource 
file mighi look something like Figure 3. 
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Figure 3. An Example Switch and Its Associated Icons , 


In addition to the icon resources, REALbasic plugins 
require you to indicate which user-defined resources will be 
used in the control. To do this, you must create a TLRm' 
resource, which lists all of the accessory resources you will 
use. To enter the data for TLRm' resources, you must first 
make a copy of the necessary TMPL T resource. The template 
resource can be found in the REALbasic plugin SDK or by 
opening a copy of REALbasic iLself. Once this TMPL 1 
resource has been added to your file, you can proceed lo 
add the necessary TLRm 1 resources. When creating PLRm 
resources, the first entry is the four-letter signature for the 
particular resource you are adding. The second entry is the 
resource number you will be using. More info on this topic 
is also available in the SDK, Figure 4 shows what the TLRnV 
resource looks like for our project. 



Once you have added these extra resources, save the file. 
We will come Irack to it later in the article when we build the custom 
control. Your plugin environment is now seL. On to programming* 


Source Code 

Our first example Ls going to perform three functions. It will 
convert an integer to Roman numerals and vice versa as well as 
convert an integer to an ordinal number. MySource.cpp begins 
with a few tindudes necessary for our plugin and functions 
called within our plugin. You will also notice some strucLs, 
which will be used later in the code. 

#include *rb„plugin.h H 
^include (string*h> 

^include <stdio,h> 

/finclude <ctype.h> 

//for Roman numerals 

struct numeral t 
long val; 
int cfa; 


static struct numeral numerals[] - I 


1L, 

T 

5L. 

■v* 

10L. 

*X f 

50L. 


I0GL* 

’C 

500L* 

* D . 

I00GL* 

’M' 


// for ordinals 

static char *text[J - I H th“, "gt". *nd H ', "rri 1 *}: 


Next, we do something a little unusual; we jump to the end 
of the source code. This is where the structure of the plugin is 
defined. The PluginEntry registers all of the methods and controls 
for your plugin. Be sure to add the letters “defn” to the end of 
each method you arc registering. 

void FluginEntry(void) 

I 

R£ALKegl£terliethod {^ConvertToOrdinaldefnj : 

REALRe gis t e r He t hod(& I nt ege rTo Rosa ndefn); 

REALfte gi Et e rMe thod {&RomanTo Int ege. r d e f n); 

I 


Continuing Lo follow the code in a backward direction, you 
will notice the RE ALMethod Definition for each of die functions 
described in the PlugrnEntry. These are descriptions of the 
functions, as they will be used within REALbasic itself and the 
corresponding function in our source code file. 

REALmethodDefinition ConvertToOrdlnaldcfn ~ I 
(REALp r oc J Con vert ToO rd i tin 1 T mw , 

REALmoTinpl emeu L u t ion. 

“ConvertToOrdinalti as integer) as string** 

Is 


REALmethodDefirdtiori IntegerToHomandefti “ I 
(REALproc) Inte ge t ToRoman func t 
REALnoTmpl^ men tint Ion. 

“TntegecToRoroardi as integer) as string" 

n 


REALmethodDefinition RomanToIntegerdefn “ 3 
{REALp r oc) RomanToI nt e gerfone. 

REALnoImplementation. 

■’RomanToInteger(a as string) as Integer” 

1; 
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Finally, we code our functions. The functions look like 
typical C/C++ functions, except that they sometimes have 
strangely named data types. An integer can be used as a 
parameter to your function (ConvertToOrdinalfunc and 
IntegerToRomanfunc) or as a return value (RomanTolntegerfunc). 
Strings being the weird birds that they are in C/C++ get special 
treatment when used in REALbasic plugins, Jf a siring is to l>e 
used as a parameter lo a function, you simply typecast the 
variable to a REALstring type. Should you wish to return a string, 
you must first define the return type as REALstring. Then, at the 
end of the function where you would like to return the string 
back to REALbasic, use REALBuildString with a character array 
and its length as parameters. As usual, a glance at the source 
code will help explain things much better than words can. 

//Integer lo Ordinal 

static REALstring ConvertToOrdinalfunc[ int number) 
l 

if ([{number %= 100} > 9 && number < 20) || {number %= 10) > 3) 
number “ 0; 

return REALBuildString[text[number]. atrlen[text[number])): 

1 


streatt roman. “M" ); 
value ■*“ 1000; 

I 

if< value >= 900 ) 

I 

streatf roman* “CM" ): 
value ■“ 900; 

I 

whiiet value >* 500 ) 

I 

strcat[ roman* ); 
value -= 500; 

I 

if( value 400 ) 

I 

strcat[ roman, "CO" ); 
value 400; 

) 

while £ value >= 100 ) 
t 

street( roman. "C" ); 

value -= 100; 

) 

if[ value >“ 90 ) 

I 

atreatf roman* “XC" ): 
value ■" 90; 

I 

whiiet value >= 50 ) 


// Integer to Roman numerals 

static REALstring IntegerToRomanfunc(int value) 
( 

int dvalue; 

char roman[SO); 
roman[0] * 'AO'; 


strcat( roman. - L“ }; 
value *=50; 

iff value >- 40 ) 

strcat( roman. "XL" }; 
value 12 40: 


dvalue * value: * , ** s T/v * 

whiiet value >- 1000 ) whlle < value 10 > 
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1 

strcal£ roman* “X" ); 

static struct numeral numeralfi[] ' 1 

i il. *i* u 

value -- 10; 

1 

l 5L. ’V* 1, 

( 10L, *X T K 

if( value >=* 9 ) 

1 SOL, ‘L* L 

1 

street( roman, "TX" ); 

f 1O0L, *C 1, 

1 5Q0L, *0' 1, 

value = 9; 

1 

1 1Q0OL, *M‘ 1 

j 

whilef value >= 5 J 

1; 

i 

street( roman, "V" ); 
value -■ 5; 

// for ordinals 

static char *text(J “ M st". "nd". “rd"l; 

1 

IfC value >- 4 ) 

{ 

//Integer lo Ordinal 

static REALstring ConvertToOrdinalfuncf int number1 

1 

streat ( roman, "1V W ); 

if ([{number V- ]00) > 9 hb number < 20) || (number %- 10) > 3) 

value 4; 

) 

number - 0; 

whilst value > 0 ) 

[ 

return REALBuildStringftext{number), strlen[textfnamberl)); 

\ 

ettcat( roman, *t" ); 
value-; 

* 

i 

// Inicgtr to Roman numerals 

static REALstring TntegerToRorumfimc [int value) 

l 

return REALBuiidString(roman, strlen£roman)): 

i 

int dvalue; 

1 

char romanL80j; 
roman [0] = '\0*: 

// Roman numerals m Decimal numbers 

dvalue = value; 

static int RomarfToIntegerfunc(REALstring nString) 

whilef value 1000 ) 

f 

int 1, j* k: 

\ 

streat£ roman, "M" ); 

long retval = 01: 

char* Str “ RRALCStringCnString): 

value -= 1000; 

1 


ifC value >= 900 ) 

f 

if £Istr |[ NULL “ ‘str) 

1 

streat( roman, "CM" ); 

return -IL: 

value * 900; 

1 

for (1 = 0. k = 1; str(i] : -Hi) 

t 

while( value >= 500 ) 

for (j * 0; j < 7: ++j] 

1 

( 

street £ roman, ): 

if (numerals[j].eh = toupper£strUJ)) 

value -■* 500; 

break; 

J 

1 

Iff value >- 400 ) 

if (7 - j) 

1 

return -IL: 

streat( roman, "CD" ); 

if £k >= 0 U k < j) 

i 

value -= 400; 

i 

retval = numerals[k]*val * 2: 
retval +* numerals[j],vai; 

1 

while( value >* 100 ) 

( 

I 

streat£ roman, "C" ); 

else retval +“ numerals[j].val: 
k - j; 

value -= 100; 

\ 

i 

if£ value >= 90 ) 

f 

if (retval<-1999) 

1 

streat{ roman, "XC" ): 

return retval; 
else 

value -= 90: 

J 

return 3999; 

whilef value >= 50 ) 
r 

1 

L 

streat{ roman, M L W ): 
value 50; 

j 


if{ value >= 40 ) 

In case you are confused by examining the code in quasi- 

1 

streat( roman, "XL" ); 

reverse order, the final code listing should appear in the 

value -- 40; 

following order: 

1 

while( value 10 ) 

i 

Listing i: MySourcexpp 

i 

streat { roman, "X" )* 
value JO: 

#include "rb_plugin.h" 

//include < string - h> // necessary for some of our string routines 

1 

i f ( value >= 9 ) 

ffinelude <stdio.h> 

^include <ctype,h> 

1 

streat( roman, “IX" ); 
value ~= 9; 

/yfbr Roman numerals 

struct numeral f 

whilef value 5 } 

long val: 
int ch; 

1; 

l 

streat( roman, "V* ); 
value -= 3; 

1 
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Iff value >■ 4 } 

I 

strcar ( roman, “IV ): 
value 4: 

I 

whileC value > 0 J 

I 

streatf roman, *1" ): 
valuers 


return REALfluiHSt ring (roman* strien(romau)); 


I 

// Roman numerals to Decimal numbers 

static int RomanToIntegerfuncfREALstrin^ nSLrlrtg) 

i 

int I. j. k; 

long retvai = QL; 

char 1 str - REALCString(nString)j 


If {Istr || NULL = *str) 

return -1L; 

for (i = D. k - -1; strfi]; ++i) 

f 

for Cj ^ 0; j < 7; ++j) 

i 

if {numerals(j],th ” toupper(strlij)) 

break: 

\ 

if (7 - j) 

return -1L: 

if (k >- 0 frfir k < J> 

r 

retvai - = numerals[k].val * 2: 
retvai numeralsfjJ.val; 

J 

else retvai numeralsljj ,val; 

k - j: 

1 

if (retval<“39993 
return retvai; 

else 

return 3999: 


1 

REALmethodDefinition ConvertToOrdinaldofn = I 
(REAhproc) Conv e rtloOrdi naif unc, 

REALnoImplementation, 

"ConvertTuOrdlnalfi as integer) as string" 

I; 

REALmethodDefinition integerToRomandefn = { 
fREALproc) IntegerToRomanfunc t 
REALnoImp1eme nt at ion. 

^'IntegerToRomanfi as integer) as string" 

1; 


REALmethodDefinition RouianToInlegerdefn = ( 
fREALp roc) RomanToln t e ge r i u nc, 
REALnoImplementation, 

"RoitLanToInteger{s as string} as integer" 


void PluginEntry(void) 

I 

REALRegisterHethodfSiConvertToOrd inaldefn); 
REALRegisterMethod{4Iut egerToRomandefn ); 
REALRegiaterMe t hod{4 RomanToin t ege rdefn): 


Now that we have covered die settings and some sample 
code, our final step is to compile it. Proceed to the Make item of 
the Project menu. If all goes well, you will find a REAUxasic plugin 
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in your MyRBPlugin folder upon compilation. If something goes 
wrong, remain calm and recheck all of your settings. Are all of the 
files named appropriately? Are all preferences set correctly? Are all 
files included correctly? Believe me, it can sometimes take the 
most time getting the compiler to behave, as you desire. 
Persevere! Of course, you can always check one of die references 
in die Bibliography for more help too. 

REALbasjc Controls 

The second example we will lcx>k at is a custom control. 
Whereas the first example only gave us three invisible methods for 
use in REALbasic, this example will add a colorful control to the 
existing toolbar. To make this control, start a new project in 
Code Warrior and follow the steps as outlined previously for 
making a REALbasie plugin. In addition, you will also need to add 
the resource file you made earlier. You should also consider 
renaming the taiget .settings so dial die plugin has a unique name. 

The source code for the custom control looks quite similar 
to the first example. There are, however, some very noticeable 
differences. We start in a typical manner by defining some 
stmets, but this time we also define the events that the control 
will receive. In our case, we will only define the Mousel Ip event 
for our simple toggle switch. This is how the event will appear 
in RKAt.basic. We also define a structure that holds the state of 
the switch (value) as well as the enabled state of the control 
(enabled). 

//include "rb„plugln.tr 

static void DrawMylcon {Rect r. short ID); 
extern struct REALcontrol myCcntrol; 

REALevent myEventad w T 

I "MouseUp(globalX as Integer, globalY as Integer)** J 
l j 

struct myData 

Boolean enabled; 

Boolean value; 

u 

Next, we define six functions. These functions are the 
bulk of the control. They define what actions occur when the 
control needs to lx j redrawn, what happens when the control 
has received one of our events, and performs initialization of the 
control One of the functions called DrawMylcon is an auxiliary 
function, hence the prototype for it at the beginning of the code. 
The initialization function sets the control to an enabled 
state and die value property to false. The value property will be 
used to tell us if die switch is an on or off state. The 
DoMouseDown and I)oMouseUp functions handle mouse events 
for die control Before MouseUp or MouseDrag events are called, 
the MouseDown function must return TRUE. DrawMylcon is 
responsible for redrawing live control As an added bonus, the 
proper GrafPort is already set up for us before rnyDraw is called, 
'thus, we can simply draw to it without any further preparation. 


The final function is called DoNothing and is included only because 
KEALbasie requires iLs presence for compilation of the plugin. This 
would normally be a REALbasic method, as seen in Example 1. 

static void raylnit(REALcontrollneLance Instance) 

I 

GontrolDataCmyControl. instance. myOata, data): 

data->enabled = true; 
data)value ■ false; 


static void myDraw(REALcontrolInstance Instance) 
l 

ContralData(myControi. instance, rayData. data); 
RGBColor oldCcl* flllCoi; 

Rect r; 

short ct rlWid th, ct r IHel ght; 

lUiALGetControlBoundsCInstance, fer); 


CtrlWidth “ r.right - r.left; 
ctrlHeight = r.bottom - r.top: 
short rarenun; 

if [ (data-) value )=t rue) 

S 

rsrcmim-1280; 

\ 

else 

l 

rstcnuurl290: 


Rect iRect; 

REALGe t Cant roIBound e(instance, &1Rer t); 

ctrlWidth “ IRecf,right LRect.left; 
ctrlHeight = iRect.hot tow iRect.top: 

BrawMylconURect, rsrenun) ; 

I 

static void DrawMylcon (Rect r, short ID) 

I 

Handle mylconSuite; 

GSErr rayErr; 

IcanAIignmentType align; 

TconTrarisfuriuType transform: 

HyErr =CetIconSuite 

(fernyIconSuite.ID,svLarge SBit+svLa rge^Bit+svLa r&eBBit); 
if (mylconSuite !* nil) 
l 

align * atTopLeft; 
transform ttKone; 

SetRect[fer T r.left.r,top,r.left! 32, r.top+^2); 

my Err 11 PlotlconSuita(fer, align, transform, raylconSuite); 

DisposeIconSuite(myIconSuHo.Lrue); 

1 


static Boolean myDoMouseDown 

(REALcontrolInstance. int x, int y. int modifiers) 
f 

return true; 

1 

static void myDoMouseUp(HEALcontrollnstance instance, int x, Int y) 

I 

Cert L roi Data(myControi. instance, myData, daui); 

Point rayWhere; 

teupVt______ 


18 


RF.AI.ramc Plugin Programming 


MacTech • Octobkr 1999 







GetMouse(fcmyWhere); 
tercpX = myWWe.h: 
tempY - myWhere.v; 


void <‘fp)(REALcoutrolInstance instance, int, int); 
fp “ (void (*)[REALcontrolInstance instance, int, int)) 
REALGetEventInstance[instance. tenyE vents[0]); 
if (Cfp) && (data)enabled)) 

l 

f p (inst ante. i empX * t empY); 

I 

I 

static void myDoNothingCREALcontrolInstance instance) 

\ 1 

Lastly; the source code defines the properties, behavior, and 
structure of the control myPmpertiesD defines the location in 
which the various properties will appear in the property panel, 
the name of the variable that will appear in the panel and the 
data type it will contain. MyBehavior describes which functions 
will be called for each of the events a control can receive. We 
will only use three; initialization, redraw, and mouseup. The lnit 
routine, as well as the Dispose routine not used here, are 
automatically called when an object is created. The other 
behaviors are listed in the SDK. Finally, the structure of the 
control is defined. KCurrentREALContro I Version is a constant 
provided by REALsofrware. The next field is the name of the 
control, as if will appear in REALbasic. Further down you will 
see the numbers 128 t 129, 32, 32. The first pair of numbers is the 
PICT' resources of the toolbar icons. The next pair of numbers 
is the initial size of the control when it is dragged to a window 
in the REALbasic IDE, The remainder of the structure defines the 
names of the associated property, method, and event functions. 
Finally, the code ends by registering the control with REALbasic. 
Save the source code and compile the control Listing 2 shows 
the completed source code for the custom control. 

Listing 2: mycontroLcpp 

#include “rb_plugin.tr 

Static void DrawMylcon (Rect r. short ID); 
extern struct REALoontrol myControl: 

REALevent myEvents!] = 1 

I "MouseUp(globalX as Integer, globalY as Integer)* ) 

h 

struct myData 

I 

Boolean enabled; 

Boolean value; 

h 

static void mylnit(REALcontrolinstance instance) 

( 

ControlUata{myControl. instance, myData, data); 

data->enabled = true; 
data->value = false; 

J 


static void myDrawCKEALcontroIInstance instance) 

l 

ControlData(tnyControl. instance, myData, data); 
RGBColor oldCol. filled; 

Rect r; 

short ctrlWid th,ctrlKeight; 

REALGetControlBoundsfinstance, Sir) ; 


ctrlWidth “ r.right - r.left; 
ctrlHeight “ r.bottom - r.top; 
short rsrcmiffl; 

if ((data->value)=true) 

{ 

rsrcmim=12SQ; 

1 

else 

( 

rsrcnuffi=l290; 

I 


Rect iRect; 

REALCetControlBoundsfinstance. &lRect); 

ctrlWidth = IRect.right - IRect.left: 
ctrlHeight » IRect.bottom IRect.top; 

DrawMylcon(IRect. rsrenumj; 

1 

static void DrawMylcon (Rect r. short ID) 

I 

Handle mylconSuite; 

OSErr myBrr; 

IconAIignmentType align; 
IconTransfonnType transform; 


tnyErr - 

GetlconSuite (imylconSuite, ID, svLargelBit+svLargeA&ii+svLargeSBi 
th 

If (mylconSuite nil) 

I 

align * atTopLeft: 
transform = ttNone; 

Set Rect (fcr.r.left. r.rop.r. left+32,r .top+32); 

tnyErr “ FlotIcoiiSuite{&r. align, transform. mylconSuite); 

DisposelconSuite(ayIconSuite.t rue); 

I 


static Boolean myUoMouaeDovn 

(REALcoutroiInstance* int x. int y. int modifiers) 

L 

return true; 

1 

static void myDoMousellpCREALcontrolInstance Instance, int x, 
int y) 
l 

ControlData(myControI, Instance, myData, data); 

Point myWhere; 

short tempX. tempY; 

GetMouseC&myWhere): 
tempX - myWhere.hj 
tempY “ myWhere.v; 


void (*fp)(REALcontroIlnstance instance, int. int); 
fp = (void {*)(REALcontroilnstanee instance. int. int)) 
REALGetEventInstance!instance. 4myEvents[O]); 
if (Cfp) U (data-Enabled)) 
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\ 

fp{i.ns lance, lempX. tempY); 

I 


static void myDoNothing(REALcontrolInstance instance) 

t 


REALproperty myProperties|3 = f 

I "Appearance”, "Enabled". "Boolean" , REALpropTnvalidate, 
REALstandardGeiLer, REALStandardSetter. FteldOffset(inyData, 
enabled)}, 

i"Appearance". "Value"* “Boolean", 

RRALpropInvalidate.REALstandardGetter. KEALstandardSetter* 
FleidOffset(myData* value)I P 

); 

REALmethodDefinllion myMethodstl - I 

[ (REALproc) rayDoNothing* REALnoIraplementation. “DoNothing" 

I, 

h 

REALcontrolBehaviour myBehaviaur “ I 
my I nit, ffthe Inil function 

nil* //the Dispose function 

myD raw * //the RcDaw function 

JityDoHou scDcjwti , 

nil, 

ntyDoMousetfp, 

u 

REALcontral *iy Control = ( 
kCurrentREALControlVersion, 

“HySwltch*. 
sizeof(mytt&ta). 

NULL, 

12SA19, 

32.32, 

myProperties, 

si^eof (my Proper ties) / sizeof{REALproporly)* 
myWethods, 

sizeof (myMethods) / eizeof (REALinethodDefillltioil). 
myEvents, 

sizeof(myEvents) / sizeof(KLALevent), 

&myBehaviour 

h 

void PluglnEntry(void) 

I 

REALRegisterControl(AmyCom rol); 

) 


Testing the Code 

“OK", you say, *l>m now what?" Well, the reason we went 
through all of the trouble to make these plugins was to extend 
our programming abilities in REALbasic itself. To rake advantage 
of our new plugins* we need to copy the plugins lo a folder 
entitled Plugins, which resides in the same folder as the 
REALbasic application and fire up Lhe REA I basic environment. 
Now t whenever you want to use the functions that we coded in 
our source code earlier, we can simply call them just like we call 
any REALbasic method* They are always available to us just as 
the native methods included in REALbasic, You should also see 
a new control in the toolbar. You can use it by dragging it into 
a window in your REALbasic project. Wow! Stop and think about 
that lor a seco nd . In a small way* you have just become a 
progra mmer o f I he R E AI basic environment. Ccx >l t eh? 


To Test our functions, open a window in REALbasic. Drag 
three PushButtons onto the window' as well as an Editfield. Theta 
add the following cotie: 

Window! .PushRuitoitl. Action: 

Sub ArrionO 

//ConvcnToOfdifui(i w integer) as string 

msglkjx editfieidl.textICon vp rtToOrdinal(val(editfield1.text)) 
End Sub 

Window l * PushButton?. .Action; 

Sub Action() 

//ImcgeiToRotnanfi as integer) as siirinj; 

mfigRox lnteaerToRoman(val (edit.fi el d i .text)) 

End Sub 

WindowI * Pushbutton3 *Action: 

Sub Action() 

//JnttjccrTnRoman(i as integer) as siring 

tns^Box strtRonianToInteger(editfieldl .text)) 

End Sub 


To test the control, drag it from the toolbar onto a window* 
Double-click the new control and add the following code; 

Window!.KySwitchl MouseUp: 

Sub KouseUp(globalX as Integer, globslY as Integer() 
me,value=not(me.value) 

End Sub 

Select Run from the Debug menu and marvel at your work. 


Conclusion 

The plugin we discussed extended REALbasic giving it 
three additional methods. We also compiled a custom control 
switch for use in REALbasic. Although both of these tasks 
might have just as easily been done in REALbasic itself, it at 
least gives you an idea of how to go about making your own 
plugins and controls for REALbasic. It would not take much 
more effort to build a custom slider control or add 
sophisticated mathematical routines to your plugin. Further 
details about the capabilites of REALbasic plugins are 
included in the SDK. You can also find a lot of assistance on 
the REALbasic users listservs which you can register for 
following the links at REALsofware’s web site. Many 
REALbasic users arc willing to offer suggestions and help 
with your plugin questions. In fact, a listserv is entirely 
devoted to plugin development in REALbasic* 

Plugins arc a fantastic addition for developers using 
REALbasic. REALsoftware knew I hat they could never cover 
every use that users envisioned, so they gave u*s a way to 
extend REALbasic* Some possible uses for REALbasic have 
already begun development, while others have never been 
attempted, given the relative youth of REALbasic. Some 
possibilities include graphic libraries, networking functions, 
high-speed mathematical calculations (for use with 3D), 
hardware support* as well as more arcane system commands 
from the Mac Toolbox. You might also find it more 
convenient to transfer some of your tried-and-true functions 
Irani yo ur . C/C+.+ l ib rar ies into a R EALb a sic plu g- i n rather than 
porting them ail to REALbasic (This was my original intention 
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for using the functions in your source code.). Developing 
controls for REALbasic can Ik* equally rewarding. The 
concepts are nearly identical to the included source code, 
but some additional code is required. Check the SDK and the 
Bibliography for further details and examples. Some possible 
ideas for controls include: custom widgets, an audio/video 
capture control, customized versions of existing controls, an 
infrared control, a speech recognition control, among others. 
Only your imagination holds you back now. 

Bibliography 

The best information available to the budding REALbasic 
plugin programmer is the Internet* A good place to begin is 
the REALbasic home site. There you can download the plugin 
SDK as well as a demo version of REALbasic, You can also 
find instructions for subscribing to the various email lists 
available to REALbasic programmers. 

RFALsoflware 

http://www.realsoftware.com 

REALbasic 

http ://www, realbasic.com 


Other sites have plugin source code, example projects, and 
compiled plugins available for download. Many of the plugin 
authors are also the same people on the listservs who will lx? 
willing to answer questions you might have regarding plugins. 

Purple E Software 

hUp://www.norcom2G00t 

Okay, I admit 1 am partial to this site, since it is my own, 
hut it docs include several freeware plugins for REALbasic as 
well as other tips and tricks. 

Essence Software 

http://www.essencesw.com/ 

Numerous REALbasic plugins, including video capture, 
QuickDraw 3D, and SuperSockcL 

Thomas Tem pelmaim 

http://www.tempel.org/rb/ 

Too many plugins to list! Loads of source code is included 
A required sire for the REALbasic plugin developer. 

Einhugur Software 

http://www.treknetJs/einhugur/realbasic/ 

Another jewel in the REALbasic community. Contains many 
useful plugins and links, HO 
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C++ Developer s Kit is a perfect tool to develop advanced 
C++ software. Using the UMl and C++ language, this Kit 
explains innovative solutions for the industry software 
t development. All C++ algorithms and software included 
in this Kit. was developed using the Object Oriented 
Software Engineering, with the UML in the Object 
j Oriented Programming. C++ Developer's Kit makes it 
easy to build algorithms for the Software Reuse, using 
UML models and C0RBA architecture 
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PROGRAMMING 


By Joseph J. Slrout, La Jolla, CA 


Learning From Leanardo 


Visualizing and 
understanding algorithms 
forward and backward 


Introduction 

Though many readers of this magazine 
will have forgotten, programming does not 
come naturally to the human mind. New 
programmers struggle with burdens at 
several different levels: learning the syntax 
of a language, comprehending the step-by- 
step flow' of program code, and grasping 
ahstraa algorithms. It's especially hard to 
learn these skills from a book or 
chalkboard; we understand better when we 
see things in action. 

A source-level debugger can let a 
student step through a program, which 
helps clarify how the computer is 
interpreting the code, II doesn't help much 
with following complex algorithms at a 
more abstract level, though. In addition, a 
traditional debugger can only step forward; 
it's like a VCR with no rewind button. This 
means that if you miss a step or want to see 
a computation again, you have to restart the 
program from the beginning. This is where 
Leonardo comes in. 

What Leonardo Does 

Leonardo is a C development 
environment made specifically for teaching 
and learning. 1l provides two major 
improvements over a traditional IDE, First, 
it provides a mechanism for visualizing 


computations graphically as they happen; by attaching graphical 
representations to key variables in a program, it’s relatively easy 
to get a high-level understanding of what the algorithm is doing. 
Second — and this is the one dial really amazes me — its source- 
level debugger runs both forwards and backwards! In addition to 
the usual step forward, step down (into a function), step up (out 
of the function), and run T the Leonardo control panel lias buttons 
to step backwards, step back out of a function, step back into a 
function, run backwards, and reset die process. 

Code written with Leonardo is completely reversible. 
Variable assignments will be undone, output sent to the console 
will disappear, graphics drawn will be undrawn, and so on. You 
have access to the full set standard ANSI functions, and yes, 
those are reversible too. The number of program steps you can 
undo is limited by available memory, but in practice, this did not 
seem to be a serious limitation, 

Leonardo does this magic by running your code on a 
“Virtual CPU* that not only provides reversible execution, but 
also catches memory errors, invalid parameters to standard 
function calls, leaks, and so on. You can't produce stand-alone 
applications with Leonardo, and programs written in it run much 
slower than they would as native Mac applications. But for 
illustrating programming concepts, or even debugging a complex 
algorithm, Leonardo’s graphical state display and reversible 
execution are hard to beat. 

Using Leonardo 

Leonardo ships as a PowerPC application plus standard C 
headers and libraries. It also comes with a large and neatly 
organized set of ready-to-run samples. 

To get a feel for Leonardo’s animation capabilities, simply 
launch the program and pick any of the samples from the 
Program hierarchical menu. Most of these illustrate common data 
structures and algorithms, like a sorted heap or the mini-max 
game-playing algorithm, but the collection also includes a few 
games and Utilities, Choosing an item will run the corresponding 
program, which comes already compiled. Most programs present 


Joe S trout works as a software developer in a neuroscience lab in southern California. While not helping to unravel the secrets 
of the brain, he enjoys pursuits ranging from martial arts to 31) modeling. He welcomes your comments at joe@srmiu.net. 
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both a text console interface, and one or more graphical displays 
to give you a peek at what's going on inside. See Figure 1 for 
a typical example (from the "KedBlackTrees” sample). 



Sorting 




Project scttl nqt 






[2 Bidirectional execution 
3 ; Auto run at program's startup 
" 3; Drbug mod# 

! consol# at program's startup 


-C 

»h 


2123 

0 

n /a 

n/a 

2484 

0 

n/a 

n/a 

6117 

469 

4243 

21 

n /a 

n/a 


figure Z Zeon^rcfo if project window (tap) 
and project settings dialog. 


With debug mode turned on, running the project presents a 
full debug console ( Figure 3) as well as a source-code display. 
This will lx.* familiar to anyone used to other source-level 
debuggers; you can step through your code in various step sizes 
(eg., step down into a function, or run until Lhe current function 
returns). The surprising controls are die buttons at lower left, 
which allow you to roll a program backwards. While delightful, 
tlie use of these buttons is staightforward and little more needs 
to be said about them. 


Figure L A Leonardo text console and graphics window. 


As a consequence of running die already-compiled 
executable, you have only a limited control paletLe and no 
access to the source code. This is fine for observing the 
graphical illustration of an algorithm, but to dig any deeper, 
you'll want a full set of controls. 

For that, use the Open C Project menu command, or simply 
double-click one of the project files in the finder (they all end in 
\p" like Lite old Metrowerks convention). This presents a project 
window similar to that in other IDEs; it lists the files in the 
project, and has buttons for running, .setting project options, and 
so on (see Figure 2 ). The first thing youll want to do is open 
the project settings window, by clicking the rightmost button. 
Project settings in Leonardo are mercifully simple; it's just a 
matter of seUing a couple of memory partitions, and toggling 
four build options on or off. I recommend you turn all four on 
— in die pre-built projects, “Debug Mode* is turned off, which 
Ls why access to die code was so limited before. 



Figure i Leonardo’s debug-made process control panel * 

The visualization commands arc another matter. The 
graphical display that accompanies most of the sample 
projects is created by embedded commands in the 
source code, in a special declaration language called 
“Alpha," While you don't need to understand Alpha to 
make good use of the sample projects, making your own 
graphical displays will require a bit of study. 
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Speaking Alpha 

Alpha commands are embedded in the C code within block 
comments. As such, they are ignored by a C compiler, bur can 
he interpreted by a special Alpha preprocessor. This processor 
sets up graphical elements and inserts calls 10 update tluxse 
dements when a relevant variable changes value. 

One starts by declaring a window tor the graphical display. 
There can be multiple windows, so each is given an ID number 
used to refer to it later, as follows: 

r 

Vlcw(Out ]>; // declare a window with U> l 
*7 

This creates a window entitled "View F to appear, as soon as 
the axle containing this block is executed. If it is at global scope, 
the window will appear as stxjn as the program runs, before entry 
into the mainQ function. When the code block containing the above 
direc tive exits, the window will disappear. The Alpha preprocessor 
acts as if it is converting these directives into C++ object declarations; 
they can occur anywhere in a code block, and they disappear 
automatically when that axle block is finished. 

A blank window is not very informative, so let's add a 
“Rectangle" declaration, based on the width of a variable, 
like so; 

// rake .1 reel wirh ITM), )eft^20, [op=l 0, 

// width=i j heighten) in vicw=l: 

Recran&le(Out 0, Out 20, Out 10, Out H, Out 10* 1} Assign 
H-l: 

Tlie frequent (but not constant) repetition of the keyword 
"Out" before parameters, as well as the need to use tlie “Assign" 
keyword rather lhan simply specifying “Our F in the correct 
position in the parameter list, are mysteries difficult to fathom 
without a complete manual (see below). However, Leonardo comes 
with literally dozens of examples of graphical displays using Alpha, 
so for most purposes you should be able to find a similar example 
and adapt it to your specific needs. My example here (shown in 
complete form in listing 1) was adapted from an example given 
in the "Read Me” document, with reference to Appendix A of the 
manual, and was fairly easy to produce. It displays the state of two 
variables with two different rectangles — a sort of dynamic bar 
graph, continually updated as the program mas. 

int mainfint argc*char' argvfl) 

l 

long j; 
long 1; 

r 

View (Oul l); // detin re n window with ID t 
// make a rect with tD=0,k'ft=2D, iop=10 t 
// widih=i, height^ 1U in vit'w=i. 

RectanglcCOut O r Out 20 , Out 10 , Oul H.Om 10 , 1 ) Assign H=i; 

// make n similar one to track j 

RemngktQut 0, Oul 20. Out 25, Out H. Out 10,1) Assign H=j; 

*Y 

for (i-0; KtOO: i++) I 

-- (i*i) % fO&T- 

) 

I 

Listing 1* 


Documentation & Support 

Leonardo is written by two developers in Italy, and is 
distributed free of charge, so commercial “level technical 
support is not to be expected. The chief support venue is the 
Leonardo web site (see URL at the end of this article), which 
is clean and well designed, and which (fortunately for most 
American users at least) is in well-written English, li includes 
an overview; a number of images, including animations; a 
program library; and an on-line manual. The manual is also 
included with the distribution. 

Unfortunately, the manual is still "under construction” 
and stops just when it was getting interesting* Only the first 
two chapters, “Installing Leonardo" and “Let's write a C 
program" are present; the rest of the manual is outlined but 
not yet available. Still, these two chapters are an excellent 
introduction to the system, and provide enough to get you 
started. There is also an appendix which provides a brief 
reference for all the Alpha predicates used to provide 
graphical output. 

Sending email to the authors appears to be Lite only way 
to get interactive support. A mailing list would have been 
nice for such a complex and powerful tool. Nonetheless, 
when I sent some questions and suggestions to the authors, 
I received a helpful response fairly quickly. 

Limitations 

Despite the version number (3 4,1 at the time of this 
writing), Leonardo is clearly not a finished product. The 
manual is mostly unwritten, and there are menu items which 
are apparently not yet implemented. For example, the 
Preferences command is present in the Edit menu but 
perpetually disabled. 

Functionally, Leonardo measures up fairly well. Its most 
serious shortcoming is that, surprisingly, there is no way to 
view or change the values of variables in the debugger. Thai 
is unfortunate; graphical visualization is very helpful for 
getting the big picture, but often one needs to inspect or 
tweak individual variables in order to fully understand the 
code. The omission of this feature will leave some users 
having to go back and forth between Leonardo and another 
IDE. In addition, it's not possible to set or change 
breakpoints while the program is running; breakpoints can 
only be set by adding a #pragma to the code and rebuilding. 
Out these were the only functional limitations found; overall 
it is quite solid. 

The interface, on the other hand, has a few more 
problems* First, it frequently displays black or red text 
against a thick marbled background, making it nearly 
illegible. This is true even for the Windows-sryle bar at the 
bottom of the screen that displays context-sensitive help — a 
poor substitute for balloon help. The windows have a very 
annoying habit of expanding to fill the entire screen 
whenever you t ouch anyth ing regardles s of whether they 
have any actual data to display in all that space. There are 
interface widgets on each document-style window which 
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look like they may he pop-up menus — and sometimes they 
are, but sometimes they aren't. Checkbox items can't he 
toggled by clicking on their text, as is usual in the Mac 
interface, but only by clicking on Lhe box itself. Also in the 
“minor quibbles” category, the integrated editor does not 
support the standard FI-F4 editing keys, and it'd be nice to 
be able to change the font. 

As a piece of software engineering, Leonardo is 
excellent; as an example of interface design, it's somewhat 
lacking. Hopefully this will improve as the program matures, 
in my email to the authors, 1 complained about some of the 
worst problems (such as the marbled background), and was 
assured that future versions would correct at least some of 
them. It's worth repeating that this is free software, and none 
of the limitations mentioned above are very serious; overall 
the quality is superb. 

Conclusion 

Leonardo is a very remarkable application. While perhaps 
not as polished as a commercial IDE, it is extremely well 
polished by the standards of free software, and it was rock 
solid in my hands. The visualization provided by the Alpha 
predicates allow one to watch an algorithm at work in a very 
powerful and intuitive way, and Lhc ability to step ordinary C 
code forward and backward is nothing short of amazing. 

This application would be most useful in computer 
science and programming courses. Tl comes with a large 


library of common data structures and algorithms right out of 
the box, ready to illustrate their workings in animated color, 
and more could easily be written from these examples. Any 
one of these could feature prominently in a class lecture, and 
is likely to engage the students and foster comprehension 
much better than abstract discussions or static diagrams. 
Since Leonardo is free, students can be encouraged to 
download a copy and play with the programs on their own. 
When they do, they'll find Leonardo's reversible execution to 
be an extremely helpful way to explore any algorithm. 

Leonardo's only real drawback is that, as yet, it is 
unfinished — a stale especially regrettable in the manual. 
The authors are doing this work with no financial support 
from Lite users, so it's the users’ responsibility to support 
them in other ways. Write to them, let them know what you 
like and don't like, tell them how r you're using it, and ask if 
there is anything you can do to help. With the concern and 
support of a strong user base, Leonardo is sure to become an 
indispensable tool for teaching, learning, and debugging. 

Useful URLs 

The Leonardo home page: 
<hnp://www.df5 + uniromalJt/-demetres/Leonardo/> 


SITEWARRIOR 

THE POWER BEHIND THE HTML INDUSTRIAL REVOLUTION 


SITEWARRIOR USHERS IN A REVOLUTIONARY NEW ERA IN HTML PRODUCTION. BUILDING AND 
MAINTAINING REAL WORLD WEB SITES HAS NEVER BEEN FASTER OR MORE FLEXIBLE 
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SiteWamor lets you bulk! HTML facto¬ 
ries that automatically create custom 
HTML code to your specifications. It's 
your own personal assembly line for 
HTML! HTML factories take the repeti 
the drudgery out of tedious tasks like 
building tables, catalogs, tables of 
contents, navigation banners, links to 
neighboring pages, calendars, even 
JavaScript arrays! 


At Site Warrior's core is a powerful 
database that makes even the 
largest web site manageable. All 
structures and links are updated 
instantly as pages are added, 
renamed, or deleted. Site Warrior even 
updates any tables of contents with 
new pages as they are added. 

Search, replace or check spelling in 
seconds across the entire site. 


"SiteWarrior gives me a tool that combines the power and 
flexibility of coding in HTML with powerful web site manage¬ 
ment and automation tools. On our latest 30 page web site, 
SiteWarrior literally saved days of work and enabled me to 
make major format changes at the last minute,” 

Keif in Killian 
Stone House Systems, 


End the tyranny. Join the HTML Industrial Revolution! 

For a free demo see [ 


provue development 
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1-714-841-7779 (overseas calls} 
email: sales@pfovue.com 
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By Thurman Gillespy III, M.D., Seattle. WA 


Tools Plus Pro Libraries + Framework 


Mac Programming Fast 
and Easy 


Overmew 

The Tools Plus Pro 5 libraries and 
(optional) application framework greatly 
simplify the development of Macintosh 
applications and plug-ins. Tools Plus 
provides a high level API dial simplifies 
and consolidates many Mac OS toollxjx 
routines. Tools Pius can be programmed in 
C, C++, and Pascal, and covers the user 
interface and event processing components 
of the Mac Toolbox. Tools Plus replaces 
the classic Macintosh event loop with an 
event dispatcher Tools Plus interface 
components include windows (including 
dialogs, floating windows, and a tool bar), 
cursors, menus, pop-up menus, buttons, 
scroll bars, sliders, panels, and list boxes. 
Tools Plus fully supports the Appearance 
Manager, but even without it t Tools Plus 
can still develop great-looking applications. 
Tools Plus supports most of the compilers 
in common use today. 

Tools Plus is developed and distributed 
by Water's Edge Software, Ontario, Canada. 
A fully featured evaluation kit (9.4M) and a 
smaller demo kit (676K) are available online. 
Water's Edge Software 
<http://www.interlog.com/-wateredg/> 

How 1 Use Tools Plus 

Eve been using Tools Plus since 
early 1996 for the development of a 


medical image display program, Dr Razz. The program uses 
many Tools Plus interface components, including the tool bar, 
floating windows, sliders, picture buttons, cursor tables, and 
edit fields. Two great ways to see what Tools Plus can do are 
to carefully study the Tools Plus Demo App (included in the 
evaluation and demo kits) to see all the user interface 
components in action, and also lo look ai my program to see 
Tools Plus used to develop a complete Macintosh application. 
Dr Razz 

<http://www.dr-r3zz.com/> 

The Out of Box Experience 

The Tools Plus distribution includes the Tools Plus 680x0 
and PPC libraries for C/C++ and Pascal. Separate libraries for 
applications and plug-ins are included. The 680x0 libraries 
have both large and small code mode) versions. Also included 
is an application framework, actually a stub application 
outline. Tools Plus supports Code Warrior (as far hack as 
version 6), CodeWarrior Pro, Symantec C/C++, THINK C T and 
THINK Pascal, and separate libraries and project files aFe 
included for these systems. 

Extras include a printed and electronic user manual (in both 
eDoc and PDF formats) and 11 different tutorial projects that 
illustrate a particular Tools Plus feature, A demo application (the 
Tools Plus Demo App) and source code arc included that nicely 
illustrate die Tools Plus event model and user interlace components. 

Tcx>ls Plus also ships with SuperCDKFs, a nice collection of 
3D user interface components that you can use to develop a 
great-looking user interface without the Appearance Manager. 
SuperCDEFs includes buttons, sliders, tabs, hierarchy triangles, 
and progress thermometers, 


Thurman Gillespy 111 ( ig^u washin^k JTi edu.) is an Associate Professor of I 
Washington, and practices at both the University of Washington Medical Center and the Puget Sound Veterans Medical Center 
in Seattle. His research interests include medical image processing and image display, When not programming or occupied 
with the day job, Ihurman is the personal chauffeur for his two teenage daughters. 
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You can divide project development into the following steps. 

1. develop DLOG, MENU and other resources for user interface 

2. write your application specific initialization routines 

3* call InitToolsPlus with appropriate parameters 

4, write the application event handler 

5, write event handlers for each window type (optional, hut 
highly recommended) 

6, write the event filter (optional, but the recommended method 
of performing menu updates) > 

7, write routines to handle application and window events 

8, link the appropriate Tools Plus library/libraries for your 
development system 

9- compile and enjoy! 


Also bundled are die Infinity Windoid WDEF, miscellaneous 
icons, animated cursors, fonts, and other resources. 

ijluillM Floating Vindov 


Figure Z A floating window created with the 
Infinity Windoid WDEF, 

Tools Pius Professional retails for $249, and includes a one 
year subscription with three annual updates, as well as a license 
to include the libraries in your finished product. The 
subscription also includes e-mail access to the Tools Plus 
Developer Forum, Water’s Edge News, and technical support. 
Support questions are usually promptly answered. Bug notices 
are automatically e-mailed to registered developers, which is a 
very nice service. Tools Plus Lite (680x0 libraries for 
Code Warrior only) is available for a limited time for $99. 
Academic discounts are available. Tools Plus Pro and Tools Plus 
Lite are available from Water's Edge and Developer Depot, 

Some Assembly Required 

So how do you develop an application or plug-in with 
Tools Plus? A great place to gel started is to use the sample 
project and the application framework files appropriate for your 
development system. The application framework is composed of 
8 files (and associated header*) that form a basic application 
shell, with lots of “insert your code here to handle,./' comments. 
The framework is entirely optional, and you can use your own 
coding style as you see fit. 


Batteries Not Included 

Tools Plus is not a complete application/plug-in development 
environment, although the libraries handle most of die event 
processing and user interface aspects of an application or plug-in, 
There is no support for memory management (except for edit fields), 
file operations, open/save file dialogs, low-levei debug support or 
network operations. Support for balloon help is incomplete, and is 
completely absent for standard algoritlims such as linked lists. 'Ibere 
is no Tools Plus API support for print operations, but the application 
framework lias useful print starter code. Tools Plus does not come 
with an interface editor like CodeWairior Constructor, RBALhasic or 
AppMaker — for serious work you will need Resorcerer from 


GOT BUGS? 

...and you're drowning in paper 
trying to keep track of them? 

You need BusLink! 

■ BugLink is a client/server application allowing you 
to connect developers, testers, and support engineers 
anywhere in the world. 

* Intuitive user interface gives you the information you 
need at a glance. 

* Fully customizable database— add the fields you need 
to each project. 

* Custom TCP/IP protocol minimizes network 
traffic— ideal for dial-up connections, 

* Client applications can operate ■off-line'— allowing 
bug entry and modification even when not connected to 
the network! 

* Cross platform— set up mixed Macintosh and Windows 
environments in minutes with no additional software 
needed! 

* Try before you buy. Download and try risk free For 
30 days from http://www.pandawave.com/bl/ 

A 5 User License starts at $299; that's only $60 per person. 

The Pand aWave 

http ://www, pandawave.com 
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$29.95 _ $24.95 $39.95 _ $34.95 


It's Disaster Preparedness Month at the Depot! 


Spotlight 1.0 New Product! New release! 

ONLY $189! 

Spotlight is a stand aione debugging aid that performs memory 
protection (arrays, heap accesses, outside your heap, low mem, 
etc), discipline checking on toolbox calls, and leaks detection. 
Spotlight is for testing of PowerPC executables, A generated 
xSYM file is needed for processing to begin testing. CodeWarrior 
and most development environments today will generate an 
xSYM file for a PowerPC project. (Spotlight does not support 68K 
executables or run on 68K Macintosh systems.) 
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BugLink Solo! 

ONLY $79! I 

BugLink Solo is a database dedicated to collecting and tracking problem 
reports. Ideal for the shareware developer. BugLink Solo allows you to 
distribute with your software BugLink Reporter, which can easily be 
configured to allow your end users to send structured bug reports directly 
to BugLink Solo. Prompt users for exactly the information you need, send 
immediate report confirmations, customize a new database to each project, 
search for related bugs with a simple query. To kill bugs dead, you have to 
know where to find them. 
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Scnpter 2.0 

SI 79 


WebTen 

$329 


FaceSpan 3.0 WebSpice Animations T PowerKey 

ToolsPlus Lite $179 WebSpice 1,000.000 $89 Mklimix Rebound 

$89 $3 


Page Charmer 2.u 
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VOODOO SERVER 

ONLY $199 

VOODOO Server is a version control system for software developers using 
Metrowerks CodeWarrior under Mac OS. VOODOO Server and the corresponding 
VOODOO clients (the included CodeWarrior VCS plug-in and the VOODOO Admin 
application) are designed to offer reliable and robust version control features while 
minimizing the administrative overhead that usually accompanies version control. It 
you're a single programmer or managing a team of developers, version control can 
make or break your project. Do it right, with VOODOO. 


DCon 1.0 

ONLY $39.95* 

DCon is a system extension that adds a console window and file logging 
services to the Mac OS. It can be used to record and display status and 
debugging information during the development process. 

DCon can be called from virtually any code, any where at any time. DCon does 
not allocate memory or otherwise rely on the Mac OS ToolBox. It can be called 
from interrupt handlers, I/O completion routines, VBL tasks, deferred tasks, and 
almost every other place you thought you couldn't use a debugger. DCon is also 
ideal for developers who miss "debugging via printf", a technique which is very 
common on other operating systems, but is not readily available on the Mac OS. 
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Mathemaes the tics. Tools Plus lias basic list box support, but Water’s 
Edge recommends purchasing StoneTable™ from StoneTablet 
Publishing for advanced list box operations. For advanced text 
handling and display you should consider the popular WASTE text¬ 
editing library from Marco Piovanelli, and for file operations you 
should consider the MoreFiles routines from Jim Luther. 

Resorcerer 

<http://www.mathemaesthetfcs.com/> 

Stone Table™ 

<http://www.teleportxom/"'Stack/> 

WASTE 

<http://www.merzwaren.com/waste/> 

MoreFiles 

<hnp://members,aol.com/jump long/> 

USING The Tools Plus System 

The Tools Plus libraries handle events and manage the 
Tools Plus interface components. To get started, you initialize 
the libraries, then let them begin processing events. 


Press Here To Start 

Getting die Tools Plus libraries up and running is easy. Your 
application’s main function may only contain 3 or 4 statements, 

TPEventRecord Event : 

void mainCvoid) 
i 

// initialize Tools Plus 

InitToolsPlus(kEvent p MyEventHandlei:♦ MyEventFilter,.♦.); 

// initialize your data structures, etc. 

InitMyAppO ; 

if tell Tools Plus to begin processing Mac OS events 

ProcessEvents0 r 

// your dean up code, if any (might be wi thin Ihe event handler) 

MyAppCIeanUpO; 

1 


InitToolsPlus goes the ball rolling, and should be called as soon 
as possible. It initializes die Tools Plus internal data structures, 
handles Macintosh startup chores for you, lets you set your event 
handling routines, and has a number of optional parameters. 

The prototype is: 


pascal Boolean InitToolsPlus f 
TPEventRecoird 
const EventHandlerProcPtr 
const EventFilterProcPtr 
short 
short 
short 
long 


•EvemPtr, 
EventHandler* 
EventFilter. 
MoreHandles. 
MaxWindows . 
TEBufferSize 
InitSpec): 


InitTooJsPlus takes a pointer to a TPEventRecord the Tools Plus 
structure that contains tile Ttx>Js Plus event information. Typically, 
this variable has global scope. The EventHandler and EventFilter 
parameters are discussed below. MoreHandles is the number of 
master handle blocks to allocate at .startup. MaxWindows is the 
maximum number of windows that can be opened at the same time. 
Tools Plus preallocates window storage (about 300 bytes/wdndow) 
and is limited to 250 windows at most (far more than any application 


could reasonably use). TEBufferSize specifies the size of text editing 
buffers (maintained by Tools Plus) used for cutting, copying, pasting, 
and storing copies of text for Edit menu Undo/Redo support, and 
should be between 255 and 32767 bytes. 

Spec is the specification parameter that specifies various start 
up tasks and Tools Plus behavior. There are 19 different 
parameters available. In my application, I initialize TooLsPlus for 
12 master handle blocks, 60 maximum windows, and an edit 
buffer of 4096 bytes. The specifications 1 use are initMacToolbox 
(initialize the Mac toolbox), initUseColor (use Color QuickDraw If 
available), initUseTEScrap (maintain a focal TextEdit scrap), 
initDontUnloadDeskScrap (don’t unload the desk scrap to disk) and 
initPureAppearanceManager (use Appearance Manager controls if 
available, resolve certain appearance ambiguities). 

InitToolsPlus(&Event, EventHandler. EventFilter, 

12 . 60 . 4096 . 

initMacToolbox + initUseCoLor + 
initUseTEScrap + InitBontUnloadDeskScrap + 
InitPureAppearanceManager )\ 

InitToolsPlus also flushes the Mac OS event queue, seeds the 
random number generator and calls MaxAppiZone. InitToolsPlus is 
typical of many Tools Plus routines: highly configurable, and 
able to handle of lot of the Mac OS “dirty work" for you. 

After initializing Tools Plus, perform your application- 
specific initialization routines. Next, call ProcessEvents to tell 
Tools Plus to start processing Mac OS events into 'fools Plus 
events. Tools Plus events are then dispatched to your 
EventHandler and WindowHandler routines (see below). 

That’s it! After three or four lines of code, your application 
is running and ready to process events. 

The Tools Plus Event Model 

After you call ProcessEvents, Tools Plus takes raw Mac OS 
events, translates them into very high-level Tools Plus events, and 
dispatches the events to your event handlers. Your event handlers 
parse the TPEventRecord, and then execute your application- 
specific code. The Tools Plus event model saves you hundreds of 
lines of code compared with handling the Mac OS evenLs yourself. 

The Tools Plus events are listed in Table 1. 

in many cases, the Tools Plus event represents the 
summation of multiple fields in a low-level Mac OS evenL T which 
gready simplifies your code. For example, it might take half a 
dozen or so steps to process a Mac OS event to determine a 
mouse click occurred in the dose box, but Tool Plus dispatches 
only one event: doGoAway. 

Every application or plug-in has a main event handler. 

pascal void EventHandler(Ptr pyCustomEata): 

The address of this event handler is passed as a parameter 
to InitToolsPlus, Your event handler typically looks like this: 

// application event handler 

if this handler presumes all window events are handled by window event handlers 

pascal void EventHandler(Ftr myCustomData) 

{ " 
switch [Event,what) \ 

case dcNothing: 

DoBackgroundProcessing C):// do background processing here 
break: 
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doNothing 

■ doChgitflndow 

No event (background processing done hens) 

User clicked in an inactive window 

^doitefresh 

: dpGoAv&y 

A window has to be ref reshed 

The dose box was clicked 


doButtcn 

Hutson was clicked 

doMenu 

Menu was selected 

doKeyDown 

doAutoKey 

rkiKevUo 

A keyboard key was pressed 

A keyboard key is auto-repeating 

A kevboard kev was released 


-do Cl IdkToEochS 1 

Mouse clicked in an object that wants the keyboard 

focus (inactive field, etc.] 

dciScrDllBar 

Mouse clicked in a scroll bar 

dahistBcx 

.Some soit of List Box activity 

i ■doaiifc” 

Mouse .click/drag [JL3| 

Pop-up mem: was selected 

doPopTjpMem.r 

doFictButron 

Picture button activity 

doClidcCoTitrol: 

Mouse clicked in a custom control 


Manually processed events 

'doMovtWindow ! 

A window was dragged by user 

iaGrowWind©'^ 

4oCiickD^«k 

A window was "grown” by user 

Mouse clicked in tbe; desk fop 

rl Tfi i.j I r' f VUr 

Zoom box w as clicked by user 

11 Q L u Oltlfl 1 Jlu UW 

doSuspend 

Appj. suspended On background) 

- doftesuse 

AppL resumed ( now active appL» 

doChgrrtf tela 

doFr^Refcesh 

‘doAetivate * 

Editing field contents w as changed 

Refresh window- before T+ objects' 

Window was activated 

doD^ct ivarc* 

•doHc-vqCursdr 

dofteylriCoxitro! 

Window' W'-as deactivated 

Cursor has entered a new Cursor Zone 

Key stroke was applied to a control 

. 116 i Jigs 

Monitor settings were changed 

d oOp en Ap p Ti ca r. ±v ri 

App launchedwith no open docs 

i doGpenDocuiriBritis 

■ doP cintDfroi iroen t 

Your app should open 1 nr more docs 

Your app'should print I or more docs 



doQ'ii.'.Ayi'l . 1 L'y l j : j). 

Your app should quit 

Table 1 

, '(boh Plus Events. 

1 

case doChgWindow; 


AcrivateWindov[Event.Window): 

break; 


case doMenui 


Hand loDnMomiO ; 


break; 


case doMuuualEverit; 


break; 



case doSuspend; 

flandleSuspendApp(); 
break; 

erase doReaunie; 

HundleResiuncAppO ; 
break; 


case doHoveCursor; 

EandleHoveCursor(): 

break; 

case doChgKonitp r Settingsi 
HandieChangeMnnitor0: 
break; 

case doKeyDown; 
case doAutoKey; 
case doKeyUp: 

// most applications don't handle keyboard events when no windows are open 
break; 

//Apple Events 

case doOpenApplicationt 
QpenApplicationC); 
break; 

case doGpenBocuments: 

OpenDocumentsO ; 
break; 

case dePrintDocuments: 

PrintDocuments() : 
break; 

case doQuitApplication: 

QuitApp(}; 
break; 
l 

} 

Alter branching to die code that handles the specific Tools Plus 
event, you often parse the TPEventRecord further for additional 
information. For example, handling a File/Open menu command 
might look like this; 

// handle menu event 

void HandlaDoMenu(void) 

{ 

swit c h {Eve nt.Menu) I 
case iFile; 

switch (Event.Menu.Itern) f 
case iNevr; 

HandleMfiwDoc.rnnfintO ; 
break; 

StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We lied, it is much more ! 

Tired of always adding just one more feature to your LDEF or 
table code ? What do you need in your table ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles for columns or rows ? 
in-line editing of cell text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make it worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today I 

Only $200.00 MasterCard & Visa accepted. 

StoneTablet Publishing 
More Info & demo Voice/FAX (503) 287-3424 

http://www. teleport, com/^stack stack@teleport.com 
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ease iOpen: 

HandleOpenDocutnent (); 
break; 

case iClose; 

HandleCloseDocumentO : 
break: 

case iFreferences: 

Hand1ePreferenees(): 
break; 
case iQuit: 

HandieQuitApp(); 
break: 
break; 
case lEdit: 

switch (Event.Menu,Item) I 
case iUndo: 

HamUeUndoO : 
break : 
case ICut; 

HandleCut(): 
break; 
case ICopy: 

HandleGopy(): 
break; 

case iPaste: 
HandiePasteO: 
break: 

case IClear: 
HandleClearO : 
break; 

) 

break: 

I 


Window Event Handlers 

An important feature of Tools Plus is die option to have 
window-related events sent to a window event handler. 1 highly 
recommend you utilize window handlers since they allow you 
to nicely modularize your window-related code. Typically, 
different types of windows have separate window event 
handlers, but windows of the same type will share the same 
handler. For example, a tool palette floating window would have 
a separate window handler, while all document windows might 
share the same handler. 

To associate a window event handler with a window, you 
create a UmversalProcPtr that points to the handler, then call 
SetWindowEventHandler to make the association. The example 
below is derived from my Preferences dialog. If there aren't too 
many dialogs in the program, 1 prefer to create Lhc dialogs at 
program startup and keep them hidden until needed. The 
window event handler won t be called until the window' is made 
visible and begins to receive user interactions. 

Event Ha ndl erllPP prefsBlgEventHandlerUFF; 
pascal void SetWindowEventllandler (short Window. 

EventHandlerUPP EventHandier); 
pascal EventHandlerUPP NewEventHandlerProc ( 

EventHandlerProcPtr userRoutine); 

// initialize the Preferences window at app start up, but don't make visible 

void InitPrefsWlridow(void) 

( 

// create dialog from DIOG resource 
LoadDialogCkPrefsWindovID. kPref&WindowResID}: 

Init_Pref s_Dialog.( ) : ff set button, check boxes, etc per user prefs 
prefsDlgEventHandlertJPP = 

HewEventHanrfle rProc(Pref sBlgEveivt Hand1e r); 
SetWindowEventHandler(kPrefsVindovTD, 
prefa D1gE v antHandlerUFP7T 
// delete UPF here if nor needed anymore 
I r lmtPrcbWmdow y 


//event handler for Preferences dialog 

static pascal void PrefsDlgEventHandler(Ptr myHata) 
[ 

extern TFEventRecord Event; 

switch (Event.What) ( 
case doButton: 

switch (Eveni.Button.Mutn) I 
case iSaveButton; 

// record user preference settings 
Save_Dialog_Fref erences 0; 

// no break after easel 
case iCancelButton: 

WindnwDisplay[kPrefsWinrfow h vHide); 
break: 

\ 

case iUseIC: 

// toggle Lhc Use intcroctConfig' checkbox 
break: 

case iUseTetnpMem: 

// toggle the disc temporary memory' checkbox 
break; 
break: 

case daPopUpMenu; 

HandlePrefDialogPopUpMenuO : 
break: 

} 


In the example above, when the user selects the 
Preferences... menu item, the Preferences dialog is made visible 
with the WindowDssplay function, and the handler begins to 
receive events. When the Save or Cancel buttons are selected, 
the window is hidden with the same Tools Plus trail. 

WindowDisplay (kPrefsWindow, wShow); //display the dialog 
WindowOisplay(kPrefsWindow. vHide): // hide dialog, don’t destroy 


Mac OS Events 

There are three occasions when you might have to handle 
raw Mac OS events. 

First, Mac OS events not handled by Tools Plus are reported 
as doManualEvents. For example, Open and Close File dialog 
update events are sent to the application event filter proc, and 
are reported as a doManualEvent, The raw Mac OS event is 
recorded in the Event field of the TP Event Record. 

// code snippet from an application event handler 
// note how the Event , message field is recast to a DialogPtr 

case doManualEvent: 

if (Event .Event what^updateEvt && OpenFilePlglsQpenO) 
DoGpenEileDialogUpdate((DialogPtr)Event.Event.message); 
break; 

Second, you can preprocess raw Mac OS events before 
they are handled by Tools Plus in an event filter that is an 
optional parameter for InitToolsPlus. A common use for this filter 
is keyboard shortcuts, Here is an example where the Command- 
Option-Shift-D key combination calls the debugger. The filter 
should return true (0) if the event has been handled and does 
not need further processing by Tools Plus, or false Cl) if the 
event should be handled by Tools Plus. 

// preproccKs Mac OS events before handled by'tools Plus 
U call Debugger!} if G immancK/prion Shift D keys pressed 
pascal Boolean EventFilter(EventRecord ‘evt) 
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\ 

switch (evt >what) I 
case keyDown:// 

if ( (evt-Modifiers & (cmdKoy | optionKey | shiftKey)) 

&& IsKeyDovn (0x02) ) If (W)2 — 1 D* key 
Debugger 0 ; 
return (0); 

I 

break: 

) 

return (I); 

) 

Finally, you have to process raw Mac OS events in the event 
filter proc of a CustomGetFile or CustomPutFile dialog. 

Apple Events 

New to version >.0 is support for Apple Events. The four 
required events are now reported as Tools Plus events: 
doOpenApplication, doOpenDocuments. doPrintDocuments and 
doQuitApplication. During InitToolsPlus, Ttxils Plus calls 
AElnstallEventHandler lo install default handlers for the four required 
Apple Events. If you install your own handler for one or more of 
these events, your handlers override the Tools Plus defaults. If you 
install handlers for any other Apple Events, Tools Plus calls the 
handler for you. If there are no installed liandlers for an Apple 
Event, Trxrls Plus reports the Apple Event as a doManualEvent. 

To determine which files have been sent with the Open or 
Print Document Apple Events, the CountNumberOfFiles and 
GellndexFileFSS routines are provided Of course, production 
code will handle any errors when attempting to open a file. 

II code snippet from an application event handler 
H handle the odoc Apple Event 

FSSpec myFSS; 

case doOpenDociinmnu;: 

for (1 * It i <= CotmtNumberOfFiles(): i++) 
if (GetindexFileFSSU, &rcyFSSi) 

HyOpenFileFroc (tnyFSS): 
break: 

I found a minor bug with the new Apple Event support If 
an Apple Event is handled, Lite event is still reported as a 
doManualEvent. WaLer's Edge lias officially reported the hug T and 
promises a fix in the nexL release. 

Tools Plus Interface Components API 

Tools Plus interface components are created with and 
referenced by an integer reference number You can use 
predefined values, or get the next available reference number. 

enum [ prefDialogic - 1 1: 

// ettate % new window with predefined rtfcioKt number 

WiodowOpen(prefDia1ogTD, ...); 

WindowDisplay (prefTHeloglD. wShov ): 

II create a new window with first free window number 
windIT) GetFraeWindowNuraO : 

WindowOpen(windID, ..,): 

WindowDisplay{vindID, uShou); 

If an invalid reference is passed to a Tods Plus routine, 
Tix>ls Plus will either safely perform a null operation, or will 


alert the user that an invalid operation lias occurred ( Figure 3)- 
With the Mac OS API, using an invalid reference like a menu or 
window handle usually results in a system crash, or worse. 


ERROR: Parameter passed to a Tools Plus routine 
is not within the legal range of values. 


Continue 


Figure Tools Plus error message if an invalid parameter is 
passed to a Tools Plus routine . 

Tools Plus also gives you complete control over the 
appearance of the user interface components, including color, 
Font, visibility, and enabled and disabled status. 

Most Tools Plus dements are created by one of four methods: 

• boundaries of the control are passed as separate parameters 

• boundaries are passed in a Reel structure 

* Ixmndaries are derived from a DLOG resource w ilh the same 
resource ID as the control reference number 

* all element parameters are contained in a MBAR, MENU, 
WIND, DLOG or CNTL resource 

The general form of these four methtxls is as follows: 

NewXXX 
HewXXXRect 
Ne wDialogm 
LoadXXX 

As an example, here are the four methods of creating a 
new button. 

If create* a button with separate parameters for button coordinates 

pascal void NewButton(short Button, short loft, short top* 
short right, short bottom, const Str25S Title, long Spec, 
Boolean Enabled, Boolean Selected): 

II get t hi non coonfi nates from Rea structure 

pascal void NewHtilLonRect(short Button, const Rent ’Bounds, 
const Str255 Title. long Spec, Boolean Enahled, 

Boolean Selected); 

II get button coordinates from DLOG item w'ith same resource number 
// as Button parameter 

pascal void NewDialogButton(short Button, const Str255 Title, 
long Spec, Boolean Enabled. Boolean Selected): 

// |?c1 hutton parameters from CN11 resource 

pascal void LoadButton(short Button, short Ren ft)); 

If the control is displayed in a window, the reference numlxrs 
arc local to every window. For example, you can have two check 
ix>xes with the same number if they are tn different w indows. 

SuperCDEFs 

SuperCDEFs are an excellent collection of high quality, 3D 
user interface components (Figure 1). There is a neat trick to ger 
a great 3D look with or wit hout the Appeara nce Manager, Choose 
the SupeiCDEFs appearance that you prefer (there are multiple 
choices), and then paste the appropriate library into your resource 


34 


Tcxus Plus Pro Liiiharies + Framework 


MacTfxjii • October 1999 















file. Next, change the SuperCDEI'V resource ID to 0. Then, 
SuperCDEFs will override the default System CDEFs, and you will 
have □ great-fcxiktng interface witli no additional effort, 

Zen and the Art of (Tools Plus) Resource Editing 

As noted above, the Tools Plus user interfaces can be 
designed with resource templates. For example, to create a 
simple Preferences dialog, design the DLOG resource and dialog 
control items (D1TL resources) in Resorcerer or ResEdiL 



Figure 4 . DLOG resource tit Resorcerer. 



□ Shaw icodJit start up 

□ Use ruted^tOintig 

Q Use tem&iiFnrv nuMnury 

r^n i »i»_j 

Figure 5. DLOG and Dill resources in Resorcerer 
Item numbers are shown. 

Then the dialog can be created witli one line of code, and 
the check boxes and button are drawn automatically. 

// usintf DLCHr resource r<> create a Prtfercoco'dLiloj* 

mum \ PtrefWindowID = II; 
enum I PrefWindowResID “ 1281; 
mum I 

iOKButton - 1, 
iCanceLBution, 
iPrefShovIcon. 

IPrefUselC, 

iPrefUseTempMenj 

1; 

LoudOialogt PrpfWindovID, PretWindovResIt)); 

The buttons and check boxes are referenced by their 
resource ID number And, of course, you will have to write the 
code that loads the user preferences and sets the dialog buttons 
based on the preference values. 

An alternate method of designing your interface witli resources 
is to use CNTTL resources. As we ll sex: in die next section, CNTL 
resources allow you to liave a great-looking interface witli or 
without the ApjK-arance Manager An example of using CNTL 


resources is illustrated in the section on pop-up menus below. 

If you are designing your interface witli resources, you 
should strongly consider purchasing Resorcerer. Using 
Resorcerer to design your program interface isn't as elegant as a 
dedicated interface editor, but its reasonably close. 

Keeping Up Appearances 

To develop an interface that looks similar with and without 
the Appearance Manager, you must use CNTL resources. Each 
CNTL resource points to a CDEF resource. For each Appearance 
Manager control you want available without the Appearance 
Manager, you must link your application with a third-party CDEF 
or WDEF resource that replicates that control. The SuperCDEFs 
and Infinity Windoid WDEF resources included with Ttxds Plus 
support Appearance Manager equivalents for buttons, sliders, 
tal>s ? hierarchy triangles, progress thermometers, and a floating 
window (Figures. 1 and 2). You must number these third-party 
resources 128 or higher so they don't conflict with the System 
resources. Then, have the CNTL resources point to the third- 
party resources rather than the System resources. Finally, link 
your project with the Appearance Manager library 
(AppearanceLibL PPC projects should “weak link" the library to 
avoid a runtime error if the Appearance Manager is not present. 

At runtime, call InitToolsPlus with the 
initAppearanceManagerSavvy or initPureAppearanceManager 
specifications. In your startup code, use the 
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UsingAppearanceManager function 10 determine of the 
A p pea ra n ce Manager s e r v i ces a re available If rh e ma nager is 
present, you can substitute the procJDs of the control 
resources so the Appearance Manager controls are used 
instead of the 3rd party resources. 

if (UBingAppearanceManagprU) [ 

ReplaCeWlndovPi:ocID(!DyToolPalfc!tteProcID t 1985); 
ReplaceControlProcllHniyCheckBoxFrocID. checkBoxProe); 
Fteplar.aDrjnr rolProclD [nsyRadioButtonProcID ( radloRutPrac); 

I 


At this point 1 must confess that my application looks so 
good with SuperCDEFs and the Infinity Windoid WDEF that Fve 
not converted my application to fully support the Appearance 
Manager. Using CNTL resources and substituting proclDs is 
definitely more work than simply using User Item resources and 
the New Dialog XXX form of Tools Plus component creation. 
However, if you want your application to suppon themes and 
other advanced Appearance Manager features, then CNTL 
resources are the way to go. 

Tin; Tools Plus User Interface Components 

Here are some of the user interface components supported 
by Tools Plus. Be sure to Itxrk at the demo app to get a complete 
look at live Tools Plus system. 

Windows 

Tools Plus supports all standard window and dialog types, 
and they can he created from resource templates, I find it 
convenient to create non -document windows like tool palettes 
anti dialogs during program startup, then simply hide and 
unhide the windows as needed. 

You can gel the Mac OS window pointer to the Tools Plus 
window with the WindowPointer function. I use window pointers 
to set die windowKind field of the WindowRecord, and to store 
document related data in the refCon field. 

WindovRpfw; 

w - Vi!>dt5wPotntc?r twindlD); 

SetWindowKimHw, kHyEocVindlD); 

SetWRefCon{v. (Ion&)myDocDataH)j 

When you are finished with and close a window, Tools Plus 
releases die window reference for future use, but does not 
actually free the Ttxtls Plus window data structure. 

Dialogs 

In Tools Plus, dialogs are simply windows with user interface 
components, Dialogs can l>c created as either modal or non-mudal. 
I prefer to create my dialogs in Resoreerer with DLOG/DITL 
resources, theri create the dialog with the LoadDialog function. 

Idols Plus also supports dynamic alerts, simple dialogs 
with only 1 to 3 pushbuttons and static text. The AlertBox 
function creates the alert and automatically resizes the alert 
dialog to properly fit the alert text. 


The Tool Bar 

Tools Plus supports a non-movable tool bar that sits 
directly beneath the menu bar. much like the CodeWarrior IDE 
tool bar. However, unlike the CodeWarrior, die tool bar w r idth is 
always the full width of the screen. Pools Plus automatically 
hides the tool bar when your application is in the background 
or if an Open or Close Pile dialog is opened. Tix»ls Plus also 
deactivates (dims) die tcx>l fear if a modal dialog is opened. 


r j File Edit Demos Help 


Wtri " al ) I fit I 1-41 fo] ill 


Figure 6, Tool Bar from the Tools Plus Demo App . 


Floating Winduw r s(!) 

Hardly a month passes on the comp,sys.mac.programmer 
newsgroups without someone asking how to support floating 
windows (Figures, 2 and 7), Tools Plus provides superb, easy- 
lo-implement support for floating windows* Floating windows 
automatically final above document windows, and are hidden 
when your application is switched to the background. Floating 
window l>ehavior is set with the wPalette spec when creating the 
window. The floating palette appearance is easily achieved 
using the included Infinity Windoid WDEF resource. 



Figure 7 Floating window from the Tools Plus Demo App 


Window Levels 

The presence of standard windows, floating palettes, the 
tool bar and modal windows adds a lot complexity to window 
management. 'Pools Plus maintains a window level hierarchy that 
determines which windows are active, and which remain 
frontmost (Table 2). 

Menus 

Tools Plus provides full support for both pull-down and 
hierarchical menus. Although there are a variety of routines for 
creating menus, the easiest method of creating your application 
menus is to create each MENU resource in your resource editor, 
tie all of them together with an MBAR resource, and call the 
LoadMenuBar function in your initialization code, Manipulating 
menus using Tools Pius is similar to using the Mac OS API, 
except you use a menu number instead of a Menu Handle. 

Ena b -I eMenu {RF11 e Hv n u , i Clos e Item. ena bled}; 

MenuMarktkOpTionsHeim* iColor. CheckChar): 

RenameTteiiftkEnlianceMenu, iToolBacItent. M \pSTiow Tool Bar”}; 
RenamolLemCkEnhancelienu, IToolBarltr-m, M \pHide Tool Bar M ); 


Tools Plus automatically handles the Edit menu when an 
editing field is active, including Gut, Copy and Paste 
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Got a bright idea? 


Got a guide? 


Got capital? 



Got buzz? 

Start up. 


Got a team? 


Got an elevator pitch? 


Kick butt. Cash out. 


it’s a jungle out there. 

Time was when two guys in a garage could start 
a company that would change the world. 

That time has gone. 

To build a great company today, you've got to 
have your act together. Completely together. 

Got what it takes? 

Join Guy Kawasaki and friends for a 2-day brain dump. 

Watch for Year 2000 
Bootcamp for Startups in 
Seattle, Silicon Valley, Austin, 

New York City, Asia/Pacific Rim, 
and Boston. 

Register online at http://www.garage.com/bootcamp 


Garage.com helps entrepreneurs build great 
high tech companies. We offer an established 
network of industry experts and insiders, people 
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Topmost Layer 
(closest to user) 

Modal Windows 


Tool Bar 


Modal windowi open at the from of tills Liver 
Multiple modal windows can be open 
simultaneous^' 

Fm utmost modal window is only accessible 
window' overriding* all others 

Always active (only one tool bar cats be open) 
Inaccessible if a modal window isopen 
Automatically' hidden when your application 
is suspended 


floating Palettes 


Standard Windows 


* Flnati ng paieties opdi at the fnm t of this layer 

* Always active 

4 Multiple floating palettes can be open 
simultaneously 

* Inaccessible if a modal window is open 

* Automatically hidden when your application 
is suspcndctl 

* Standard (modeless. nomool bar nomfloating 
palette) windows open at the from of this layer 

* Only the front most window in this layer is active 

* Multiple standard windows can he open 
simultaneously 

* When running under System 5 or 6’S finder 
desk accessory windows may appear in this 
layer providing a iool bar or floating palette is 
not open 

* Inaccessible if a modal window is open 


Table Z The Tools Plus window layer model. 


operations to and from the Clipboard, and Undo/Redo 
support for the last edit operation. 

Water's Edge recommends lliat you update the status of your 
menu items in the event (liter when the user dicks the mouse in the 
menu liar for maximum performance. Thai way, user actions tiiat 
result in menu items lxing enabled, disabled, added, or deleted — 
such as menu item check marks appearing or disappearing. — won't 
Ixr perforated until just befoie the user actually .sees the menu. 

// filHT Mac OS events before pnH. L e»ing by Tools Tins 
// update all menu items when the user dicks in the menu fair 

pascal Boolean EventFilter(EventRecord B evt) 

{ 

WindowRef w; // just a place holder for findWindnw 

switch (evtOwhan) I 
case loouseDovn: 

if (FindWindow{evt->vhere. &w) InMejmSar) 

HylJpda i etftenuProC t) ; 
break; 

] 


retu rn (1); // Tools Plus should continue to process this event 

[ 


However, changes to the menu bar should lx peifonned more 
promptly. For example, when all document windows ate closed, die 
Edit menu is dimmed in many applications. Fortunately, Tix>ls Plus 
updates the menu Ixtr after an event handler routine finishes 
whenever the menu Ixtr lias btxm changed with die Apple Menu. 
Menu, RemoveMenu. or BnableMenu routines. 

My major annoyance with Ttx>Ls Plus menus is the inability to 
show multiple-key menu item shortcuts in a menu. This 
shortcoming could lx* readily fixed by the Metvutio MDEF, but, 
unfortunately, T<x>ls Plus is not compatible with Meiuutio. Water's 
Edge Ls investigating the Issue, but liave nol committed to a 
MeruiIk><ornparibtlity release date. 

Mercutio MDEF 

<hrtp://vwvw.digitalalcfiemy.com/merciitio/> 

Pop-Up Mentis 

Pop-up menus are a great user interface feature that allow a 
.selection from multiple choices in a compact region of a window or 
dialog. In addition to Mac OS standard pop-up menus, Tcxtls Plus 
pop-up menus have additional options, including displaying ihe 
selected item's icon within the pop-up Ixxx, suppressing the pop-up 
menu's "down arrow”, and a "pop down" option where the menu's 
list opens below tlx* menu body. 



Figure & Pop-up menus from (be Tools Pins lk>mo App. 

I create my pop-up menus with die LoadDialogPopUp function 

LoadDialo^Foptlp(short MenuNuinber. long Spec, short ResID); 

Menu Number is rhe menu resource ID, which must he 1600 
or higher. Tools Plus uses the coordinates of the resource 
identified by ResID - in Resorcerer, I use a User Item - to draw f 
the pop-up. Spec is the pop-up specification that defines ihe 
pop-up appearance and Ixhavior Options I use include 
popup3DBody (3D look available in all system versions), 
popupUseWFont (use window font) and popupIconTitle (use the 
menu item icon in the pop-up box). Unfortunately, the pop-up 
menu title is drawn to the left of the user item rectangle, so 
getting the pop-ups lined up correctly in your window takes a 
few edit-comp ile-nirt cycles* 
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Water’s Edge recommends using CNTL resources as the best 
method for creating pop-up menus. Hie manual is a bit sparse 
on the details, hut here are the steps (using Resorcerer): 

* Create and place a new Control item (Item menu) in the 
window where the pop-up box will be drawn. Ihe menu 
title will be drawn to the iefi of the lx>x. 

* Sdect the item, then choose Get Info from the Item menu. A 
Control Item dialog will open. Enter the CNTL resource 
number in the Res, ID edit Held. A new CNTL resource will 
Ire created if one does noi exist. 

* Click the Edit button, and edit the (new') CNTL resource. 

* Change the CDEF Res ID field to 63, which will generate a 
ProclD of 1008. 

* Change the ‘MENU’ ID field to die number of MENU resource 
used by the pop-up (must be 16000 nr higher). 

* Enter die name of the pop-up menu in the Title field. 

* Set the Style code and Title width fields to 0. 

I struggled to get CNTL resources and pop-up menus to 
work correctly until I discovered two crucial tips: 

1. you must set the Conform 'CNTL' bounds to Control item 
bounds dialog editor preference (Dialog/Preferences...) in 
order to synchronize resizing the Control item with the 
CNTL resource. 

2. Style code and Title width fields must lie set to 0 (Resorcerer 
may choose an inappropriate default). Frankly, CNTL 
resources are significantly more complicated than using User 
Item resources with Load Dialog PopUp. 

Cursors 

Cursor shapes are easily changed with the CursorShape 
routine. There are defined constants for the standard cursor 
shapes: arrowCursor, iBeamCursor, crossCursor, plusCursor, 
watchCursor. Ttx)ls Plus automatically changes the cursor shape 
when the cursor is over an edit field. 

pascal void CursorShape (short Shape]; 

r fhc watch cursor has special status. When you change the 
cursor shape to the warch, Tcxils Plus is alerted that "a lengthy 
process in underway." If the watch cursor is active, die cursor shape 
will not be changed automatically by T<xis Plus. Most events are 
filtered and not sent to the application event handler except for 
Command-period, to allow tltc user to cancel a lengthy operation. 

Cursor Tables and Zones 

A powerful feature of Tools Plus cursor management is the 
ability to define regions where the cursor automatically changes 
shape. TcxjIs Plus uses cursor tables, which contain one or more 
cursor zones. When the cursor enters a cursor zone, it changes 
to the cursor shape defined for that zone (Figure 9). The zones 
are defined in local window coordinates. Each cursor table has 
a default cursor that is used if the cursor does not fall within any 
of the cursor zones. A cursor table is associated with a window 
by the UseCursorTable routine. 


1 This is a "Plus Cursor* \ [ This is a "Plus Cursor M j 

j zone. The cursor changes j j zone. TtcJJiursor changes j 

j when entering this area. j when entering this area. 

Figure % Cursor Zone Example. When the cursor moves 
inside the cursor zone, the cursor shape changes from 
an arrow to a plus shape. 

I use cursor tables to support cursor shapes for different rix>ls. 
At program initialization cursor (allies are defined, and linked to the 
cursor resource associated with each tool. I lowcver 1 don't create a 
cursor zone for any of die tables. When the tool is selected, 
UseCursorTable associates the proper (able with the image window, 
and tire cursor shape automatically changes !t> the proper Ux>l when 
the cursor moves within the window (Figure 10) 

// program start up 

it establish cursor tables far catib kxj! 

ft cursor tables 

cmim I 

SelecticnTable - 1. 

CrabberTable* 

MagnifyTable, 

PencilTable* 

PaintSrushTwble 


ft resource IDs for cursor shape* 

ersum E 

GrabberKeslD = 128,. 

HagnifyRcsID, 

PencilRasin, 

BrushResill 


'IN JUST A FEW SECONDS I'VE SUCCESSF^LLV TRACKED 
DOWN A MEMORY CORRUPTION BUG THAT HAS BEEN ELUD¬ 
ING ME FOR ABOUT 3 MONTHS- FANTASTIC >) M 
-Bryan Christianson- 


5P0TLIQHT 


The #1 Macintosh bug detection tool! 


• Detect memory leaks automatically 
■ Instruction level bounds checking 

• Validate 400 Mac Toolbox calls 

• Pinpoint stale handle usage 

• Integrated with all Mac debuggers 

• Debug shlibs and stand alone code 

• Faster than ever before 

FREE it 

DEMO 
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// set up llie cursor tables, associate table with default cursor resource 
NewCursorTablc(SclectionTabie. arrowCursor): 
NewCurf;orTEibl^(GrabberTable t GrabberReslO J; 
NRwGLiisorTableiMagnifyTable, MagnlfykesIB)' 
NewCuryorTable(PeticilTable, PeticilKesID): 

Nt'wCursorTable(PaintBnushTable, BrushResID); 

// application event handler 

// w hen a tool is selected, associate the proper cursor table with the image window 
// in this example, the Magnify tool b selected 

DseCurfiorTabletfrontlEiiageWindowC) , HagnifyTable): 

SSSEIZIZH] I 


Figure 10, Cursor fable example. The magnify tool is selected. 
Cursor shape is arrow when the cursor is outside of window, 
and changes to magnify glass when moved over window. 

Every Picture (Button) Tells a Story 

Some of my favorite Tools Plus features tire picture buttons 
— click-sensitive icons anti PICT resources. This versatile control 
permits a wide range of button types, including pushbuttons, 
dick-sensitive icons, multistage buttons, radio-type buttons and 
polarized buttons (button value increases or decreases 
depending on which part of the button is clicked). Picture 
buttons are an easy method of creating greaL-kx>kmg tool 
palettes (Figures 6, 7 and 10). 

Picture buttons are a bit more complex to set up )x*cause of 
the many different button types and behavior options available. 

I create my picture buttons with lire NewDialogPictBuUon routine, 

pasral void NewDlalcgFietButtcm £ 

short Button ID, // IVtuie button number 

abort EaselD. // Base image s resource ID 

1 on g S pe c, // Appearance and Behavior spec 

Boo lean Enab 1 ed 3' big. // ‘ But ion is enabled ‘ Hah 
B oolean SeI ee t ; ed ¥i ag. //Thitum is selected" Hug 
short minimum. //Minimum button value 

short value. // Initial button value 

abort max imm); // Maximum button ^ue 

The button s coordinates are obtained from Lhe dialog item 
whose number matches the button numf>er, ButtonlD. BaselD is 
the resource nurnlxT of the icon or PICT resource of the button, 
and Spec is the behavior and appearance specification, There 
are 30 different specification parameters for customizing the 
appearance and behavior of the button. 

fools Plus can support more tlian one icon or PICT resource 
for a picture button, For example, the active, inactive, and dimmed 
states of a button may have a different image, and multistage 
buttons will of course have a different image for each stage. Tools 
Plus handles multiple resourc e s for picture buttons b y-using a 
resource numbering sequence system to determine which resource 
is associated with each stage and appearance of the button. 


The picture button type I find most useful is a 3D button 
created with SIGN icon resources, which 1 use for a tool 
palette on a tool bar window r (Figure 10). Tools Plus 
automatically creates a color, 3D button from the black & 
white SIGN icon. The options 1 prefer for my Lool palette 
include picbulLockSelect (lock button in selected state until 
another button selected) and pcitbutSlectLightenSICN3D 
(lighten and “push in" button when selected). 

Fieidfs) of Dreams 

fools Plus text editing fields are powerful Tools Plus 
automatically handles many routine edit field tasks, including 
field aaivation/deactivation and low memory protection. Fields 
can store up to 32k of text each. To save memory or improve 
performance, you can limit the field text length Lo a much 
smaller number, or can have a text handle that automatically 
resizes as text is entered, hither Pascal or C strings can be used. 

When you enter or change the text in an edit field, you are 
working on a copy of the field text. 'Hie changes are not saved 
to the edit field string until the edit fie:Id is deactivated by 
clicking or tabbing to another field, or dosing the dialog with 
the field. You can optionally lx* notified when this occurs to 
perform field validation, Fields can be placed in any window 
that you create, Tcxil Plus ensures that only one field — the 
active field — is active and selected at a time. 

Another great feature of Ttx>ls Plus is its field filters. Filters 
allow you Lo limit what characters can be entered into a field, 

pascal short MewlfieidEil ter (const StrlSS Chars, 

long FllterSpec); 

NewFieldRlter returns the field reference number, Chars 
specifies die diameters to lx a included in the field, and Spec 
allows various text filter options. Filters and length-limited fields 
are a great help when designing a data entry form. 

A problematic aspect of edit field management Ls validating 
field contents. You can have Tcxtls Plus notify you when the 
active ediL Field is about to lx.* deactivated. If you don’t need to 
validate edit field contents, then you should call InitToolsPlus 
with the initAutoFocus specification, and Tools Plus will 
automatically update field contents. 

If you don't use the initAutoFocus option, there are two 
cxcusions when Tools Plus notifies you when the user is about 
to deselect an active edit field. First, when the user clicks in an 
inactive edit field. Tools Plus sends your event handler a 
doClickToFocus event. The GetEditString function returns a handle 
to the temporary copy of the active edit field string. If the field 
siring is validated, you save the changes with the SaveFieldStiing 
function, and allow the new edit field to be selected with the 
ClickToFocus function. 

// example of field validation 

// example is for j form with a name and e-mail edit tie Id 

pascal void GetKd 11 String (Str255 EditString); 

pascal void ClIckToFucusTvoid]t 

-pas c al void Sdv e Fi e ldguittg(vuld): " 
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// window event handler 

case doClickToFocus: 

if £MyVaiidateFieldProc()) I 
SsveFieldString(J; 

ClickToFocusO : 

) 

break; 

short MyValidateFieldProe[void) 

I 

Str255 string; 

short fieidNum = ActiveFieldtfurnberO ; 

GetEditString(&string): 

switch (fieldNum) [ 
case nameField: 

if U IsNaJiieFioldVal id(Fitring)) I 

Alert("Invalid name field, please reenter.*): 
return false: 

J 

break; 

rase e mailField: 

if (! TftViil IsdEmailAddress(string)) I 

Alert ("Tnval id e-mail address, please reenter.*); 
return false: 

I 

break: 

j 

return true; 


Second, if the user pressed ihe Tub key to move to the next 
field tor pressed Shift-Tab to move to the previous held), you 
use die HaveTablnFocus function to determine if die key press 
occurred in an active edit held. If the field contents are 


acceptable, you save the field changes with SaveFieldString (as 
before), and use TabToFocus to allow die user to tab into the 
next or previous field. 

pascal void UavcTabTnFocuaCvoid); 

// window event handler 
case doKeyPown: 
case doAutoKey: 

if (HaveTablnFocusO) t 

If (HyValidateFieldFroc £)) I 
SaveFieldStringO ; 

TabToFocus (): 

I 

1 

break; 

Scroll Bars and Sliders 

Tools Plus provides excellent support for managing scroll 
bars and sliders, a problematic aspect of the pre-Appearance 
Manager Mac OS API. You can use the default system scroll bar, 
or you can use third-party CDEFs like those provided in 
SuperCDEFs. SuperCDEFs has a nice selection of sliders (Fig. 1). 
Tools Plus also supports "live action** scroll bars, and scroll bars 
that automatically resize when a window is resized. 

When a scroll bar or slider is moved or clicked by the user, 
a doScrollBar event is reported. The event record also reports 
which part of the scroll bar or slider was activated. Your event 
handler will continue to get doScrollBar events as long as the 
user keeps moving the scroll bar thumb with the mouse. 


The most powerful Email and Webform management tool waitable! 
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A better method of handling scroll bar and slider events is 
to use an action routine which Tools Plus calls for every user 
interaction with the scroll bar. The action routine is Jinked to the 
scroll bar with die SetScrollBarAction routine. Within the routine, 
you use the GetScrollBarAetionlnfo routine to determine which 
scroll bar is active, the parent window of the scroll bar, the part 
moved or clicked by the user, and whether the mouse is still in 
the original scroll bar part. Action routines are another method 
of developing nicely mcxlularized code in Ttxils Plus. 

// prototypes 

// Create a UPP to a scroll bar s action routine 

pascal ScrollBarActicmtJFF NpwScrollBarActionProc 

(ScrollBarActionProrPtr userRoutine); 

// Set an action routine for a scroll bar 

pascal void SetScrollBarAction (short SerollBar. 

Scroll HarActicmUFP ActionProc): 

// Get info ahom the scroll im currently caDmi; an action routine 
pascal void GetScrollBarActionlnfo {short ‘Window, 
short *Scroll Bar* 
short *ParU 
Roolean *inPart); 

// create DPR attach the aciion proc to the scroll bar 

ScrollRarActionllPF MyAetionProdJPP: 

MyAct IonProctiPP = 

NcwScrollBarActlonProc(MyActionP roc); 
SetScrollBarActionOtHyScrollBar* 

MyAct: ionProctiPP); 

ft typical structure of sen >11 bar action pnxr 

pascal void MyActionProc(void) 

t 

short scrollBar. part* curVal, vindTD: 

Boolean inPart; 

static short oidVal = 0; 

GetScrolIBarAetionlnfoCkvindlil, trscrollBar. 

&parl, AinPart); 

If {!inPart) 
return; 

If fier the current value of the scroll bar jiutfinl to the action prt>c 

cnrVal = GetScroiiBarVal(sctollBar); 
switch (part) t 
case (inThumh): 

if fcurVal — oidVal) 
return: 

// handle in rhumb action here 

break; 

case (inFagellp); 
case (inUpButton); 

// handle pa^c up action here 

break; 

case (InPageDown): 
case (inDownRiir loti): 

// handle pgr down action here 

break; 

I 

oldVal - curVai; 


Misceiianeous Stuff 


Documentation 

The Tools Plus documentation is excellent. There are 
overview chapters ort setting up and using the libraries, and 
specific sections for each type of interlace element. Both printed 
and electronic versions (eDoc and PDF) are supplied. There is a 
nice touch to the electronic documentation 1'vc not seen before 
- the pages arc numbered consecutively from the title page, so 
that when you select Move to Page... (eDoc) or Go to Page,.. 
(PDF)* the Table of Contents page numbers and the electronic 
page numbers are synchronized 1 think a few more axle 
examples would be helpful, but there is plenty of code to study 
in the demo app and in the tutorials. 


Whither Caribou? 

Water’s Edge slates that Tools Plus is already highly Carixxi 
compliant, and full Carbon compatibility should not lx* a problem. 

Summary 

Living with Tools Plus 

Fvc enjoyed working with Tools Plus and Water's Edge 
f>oftware. The quality of the libraries* the documentation and the 
technical support is excellent. Tools Plus greatly simplifies the 
task of developing Mac OS applications and plug ins, and lets 
you concentrate on coding your application, Fm impressed with 
how r much of the “dirty work" of Mac OS programming the Tools 
Plus system handles for you. 

I've submitted about half a dozen bugs that have been 
acknowledged, fixed* and logged in the changes file. Most of the 
hugs Fve encountered have been minor and easy to work 
around. 1 find it helpful to knock off a quick mini-application to 
send to Water’s Edge that isolates a particular problem* and with 
Tools Plus, the application is easy to create! 

My two major complaints with Tools Plus are the lack of full 
support for balloon help (scheduled for Sept. 99 release) and the 
inability to have multiple-key menu item shortcuts (under 
investigation* but no release date announced). Some features I'd 
like to see include Open/Save File dialog support* preference 
file support* and some examples of how to make your 
application scriptable. 

Recommendations 

1 strongly recommend the Tools Plus system. But is Tools 
Plus for you? Here are some points you should consider, 

* What language do you program in? If you are better at 
programming in C or Pascal than C++, then I'd lean towards 
Tools Plus, If you are good in BASIC, Fd take a peak ar 
REALbasie. If C++ is what bakes your ax>kies, then you 
might be more comfortable with a complete application 
framework like PowerPlant. 

* Do you have strong beliefs about your coding structure and 
style? A code generator or application framework will impose 
its programming worldview upon you* whereas Tools Plus 
allows you to program in the style that suits you Ixst. 

* What about PowerPlant? PowerPlant is a more complete 
application development system* but it is significantly more 
complex to learn than Tools Plus* You will be up and 
running much faster with Tools Plus* but down the road you 
will have some programming chores to do on your ow r n that 
PowerPlant would have handled for you. 

* Are you a Windows programmer new to the Mac? Welcome! 
Tile Tools Plus event model resembles the Win 32 messaging 
system* so 1 think your Windows programming skills will 
serve you well if you choose the Tools Plus system. 


Whatever your choice* good luck on your programming 
projects. fij 
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FROM THE 
FACTORY FLOOR 


By Hric Cloninger and Dane Mark, ©7999 by Metrowerks, Inc., all rights reserved 


A Palm Update, Part 2 


Last month’s Factory Floor got us back in sync with the Palm 
development universe. We checked ouL some of die new features 
in ihe upcoming Palm OS SDK and CodeWarrior for Palm OS 
releases. This month, Erie Cloninger will take us through the 
process of developing an internationalized Palm OS application. 

Eric Cloninger is the product manager and technical lead for 
CodeWarrior for Palm OS. When he isn't working on CodeWarrior, 
he spends way too much time on his research project — how to 
rid the world of the affliction known as the "designated hitter mle\ 
lie can be reached at ericc@metrowerks.com. 

Dave: fell me alxml the application you 1 II be taking us 

through. 

Eric: This month, I'm going Lo go ll trough an application I 

wrote using CodeWarrior for Palm OS Release 6 (available in 
October 1999)* The application, called Base X, takes 
advantage of several new features that Palm has added to the 
OS, the SDK and the tods. 

Since our goal is to make an international Palm OS 
application, 1 chose an example that is simple to describe but 
is also useful in a real-world sense* This example, called Base 
X T provides four edit fields that display the same 4 byte value 
as decimal, hexadecimal, tx:Lal, and binary. In addition to the 
user interface elements on the main/em, Base X lias a menu 
bar, an alert and an info string, all of which have been 
localized from English to German, French, and Japanese. 

1 started by creating a new project from the "‘Palm OS C App" 
stationery project. CodeWarrior for Palm OS provides 
stationery projects for Palm OS 3-1 (for the original Pilot, 
PalmPilot, Palm III, and Palm V), Palm OS 3-2 (for the 
wireless Palm VI I), as well as Japanese examples. 

I renamed the resource file to BaseXenglishrsrc and opened 
it with Constructor For Palm OS. Construc tor for Palm OS is 
very similar to Constructor for PowerPlant — you can create 
menus, menu bars T pictures, icons, etc. In fact, all of these 
elements use standard MacOS resource types, .so you can edit 


them with Res Edit or Resourcerer. The tiling that is unique 
about Constructor for Palm OS is that it lets you create the 
Palm-specific resource types rim define how forms look. 
Figurc 1 is from Constructor for Palm OS — it shows the main 
form for Base X as it appears in the English resource file* 



Figure L Constructor for Palm OS editing a Palm OS form * 

After I created the user interface, I moved the resources that 
are language neutral into a separate resource file called 
BaseX_Common.rsrc* Then, 1 moved the English resource file 
into a directory named “English"' and duplicated it for German, 
French, and Japanese and renamed the files appropriately. 

In my CodeWarrior project, I created four targets, one each 
for English, German, French, and Japanese. Next, 1 added the 
common resources to all four targets anti the language- 
specific resources to each of the language targets. At this 
point, for eadi target 1 have a source file, a common resource 
file, and a language-specific resource file, I have not yet 
written any code to operate my user interface, but the starter 
application lias enough code in it to display my form. 

Next came the localization part. First, I browsed to 
bahdllsh.aliavista.com and tried their web interface. Die engine 
dial provides the translation on the web page Is available as a 
commercial product called SYSTRAN. I used the web interface to 
convert my strings, l>ut I found that the translations weren't quite 
right and it doesn't translate to Japanese. Since Metrowerks has 
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offices in many parts of the world I asked employees to do the 
translations instead 'Ihese employees aren't in our Austin office 
and they didn 't have immediate access to the Palm tools, so 1 had 
to find a way to gel the strings to them easily. 

Using the OxJeWarrior IDE f l created an empty target in my 
project called “DeRcz". Then l atkled the English resource file to 
that target and changed the settings for tire target to use the 68K 
linker (to activate preference panels — no linking occurred in 
this target). Next, I dtanged the “File Mappings* panel so that 
files of type “PLob" (Palm OS Constructor files) are compiled 
with the "Rez” compiler. Finally I entered a file called 
PalmTypesx lor ihe Prefix file in the Ttez* panel. I saved these 
settings and returned to lire “Files 71 view of the project window. 

From the files view, 1 clicked on BaseX_english.rsrc and held 
the mouse button for a second until the pop-up menu 
appeared with an item called “Disassemble 1 *- The Rez 
compiler will disassemble resource files into r files if it has 
type definitions for the resources, which is what PalmTypes.r 
provides. The result of the disassembly is a new text file that 
1 sent to my colleagues. PalmTypes.r is available from Pal mV 
developer web site, by the way 

I knew it would lie several thousand Swatch beats before 1 
got my replies back, so 1 decided to jump into the 
programming task. 

Base X has four edit fields into which the user can enter text for 
decimal, hexadecimal, octal and binary numbers. When the user 
enters a character, Base X sees if the character is valid for the 
field with the edit focus and converts all die fields if it ls t The 
code for all of liaseX is too long to include in tills article, so I've 
put it on Metro works web site at the address shown at the end 
of tills article. The axle segment below is the pan that converts 
strings from one base to another and Is where I tiad to use the 
Palm OS internationalization manager, 

//This struct dcHTihcs hi w to convert brings 
// into different ha*cs It's OK (be ihis lo k 
// single hyte chars because it’s never shown. 

struct f 
char 4 di&its: 
char multiplier; 

) evtTableDI - I 
("tn234H7&9”, 10], 

E“Ot?.:UW890bcder\ 161* 

[-Di mw, HI. 

ror, 2i 

u 

// Convert a string to a number using base V 

ULong ToLongtWChar *Btr, short £able_index) t 
unsign#*! tong accura = Q; 

WChar ch = 0; 

short str_index = D; 

short accum_index * 0; 

// Go through the input string, pull each 
// character off and find the index of that 

// character in the rahkv Thai index is- 

// the amount to add to the accumulator 

while (str_index < EDITVSIZE) I 
str^index TxtGlueGetNextCharE 
(Char *) Str, Str index, krh); 


if (ch) 

1 

accunLindex = 0; 
while ((acorn index < 

StrLert(cvtTab]e[table_index] .digits)) bb 
(WChar) 

cviTable[table_indexj.digitslaccum_index1 
T= ch) 

accum_index-H-; 

accum cvtTablefrable_Jndex] .mul L Lplier; 
accum t= accum_ index; 

I 


return accura; 

1 

// Creates a siring of base V from a long value 

void To&tringUJUmg value, WChar *str, short table_index) 

I 

shod masked_value; 
char tenp_str[EDlT_SlZEj; 
char *p = temp_str: 
short str_index = 0; 

while (value >0) | 
nasked_value ~ value % 

cvlTable[table_indexj .multiplier; 

*p++ = cvtTableftable_index3,digitsImasked.value]; 
value /= cvtTableltabie_indexl.multiplier; 

) 

l/At this point, [cmp_ttr is in reverse order 
// Create output by walking tcmp_str in reverse 

str_index ^ 0; 
while ( p >= lerap_str) 
str_index += TxtGiueSetNextChar( 

(Char *) str. str index. (WChar) *p); 

I 

The functions prefixed by TxtGlue 1 are notable because they 
arc implemented through a library called PalmOSGlue.Itb 
instead or the A-trap mechanism used by mast of the OS 
calls, 'ITiese functions are safe to use on devices mnntng 
version 2.0 or later of rhe Palm OS, regardless of whether it 
Ls a single-byte or multi-byte OS, 

liy the time i had the code working for English, my translations 
were d< >nc. Thanks to Andreas Hommel, Christophe Escobar; 
and Shoji Ueda for providing tills service. Next came the task of 
gening the converted resources into the project without re- 
entering die text myself. 

Developers who work with localized applications are faced with 
tiie same situation I found myself in — whether to keep legalized 
resources in a text file where the text tan be mtxltfied easily, or 
to keep them as resource files where their properties can be 
mexiified with a visual editor Either method is fine and 
QxleWarrior allows me to use resource files or Rez files, so 1 
chase to set up my project so tlial I could use either methrxl 

I created a new target called *Hez French’ cloned from the 
Trench’ target. I modified the settings so that the outpur file 
created by the MacOS linker is different from the output file 
generated by the resource file target 1 also modified the 
Tez panel to indude the TalmTypes-.r* file as the prefix file. 
Into this target, I added the translated RaseX_french.r file. 
Then, 1 built the project. 
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The output from the linker and post linker was the translated 
Palm OS application. An artifact of the build process is a file that 
also contains all my applications resources before they were 
modified by the post linker. I opened tills intermediate file, 
called FSaseXRsR' tmp, with ResEdit and copied all die resources 
except CODE 1 and ‘DATA 1 into my French resource file named 
BaseXJtendi.nirc. Al tills point, 1 can create a French Palm OS 
application using either die ,r file that is compiled by die Rex 
compiler or I can build the same application using resources 
included from die Constructor file. Next, I duplicated this work 
for die English, Gen nan, and Japanese targets. 

After building my applications, I want to run them and see how 
they work. I could download diem individually to my Palm OS 
device over die serial connection or I can use an extremely 
useful application called the Palm OS Emulator ; or POSE for 
short POSE is an application that contains a 68K emulator and 
it runs the Palm OS image diat is in ROM. You must own a Palm 
device to get the ROM image, which is downloaded from your 
Palm device using an application called ROM Transfer. 

Figure 2 shows the Palm OS Emulator running the Japanese 
version of BaseX, Any Palm device is capable of displaying 
English, French, and Gcnnan applications. Japanese applications 
require a Japanese-enabled ROM to display tire text correctly. 



Figure Z Palm OS Emulator and CodeWarrior debugger. 

Lefs suppose that I decide I don’t like the way one of the 
Japanese screens looks — perhaps I want to change the text 
of Lhe info siring shown in the alxxit box. Instead of sending 
the text file lo Tokyo where it’s early in the morning, I use 
Constructor for Palm OS to modify the strings myself. Palm lias 
modified Constructor to w ork with die Japanese Language Kit. 
With the JLK installed on my Mac, l need only change the 
selection for the “Palm OS Target" in Constructor Lo u Palm OS 
for Japan” and then 1 can begin editing in Japanese. 


Now, I open the editor for Lhe sLring that I want to modify. I 
select Japanese mode input by clicking on die blue triangle on 
the menu bar in die upper right corner. As 1 type, the MacOS 
pops up a text entry window' that converts the ‘sounds’ 1 am 
typing inLo the correct characters, as shown in Figure 3. 


□ ; _ : String IGOG, "Created for Help ID" .S 

Note: "Viev As" information is not saved. It is for display purposes only. 
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Figure 3- Constructors' siting editor with Japanese text input. 

At tins point, BaseX is completed. I hope that Eve been able to 
show' that Code Warrior for Palm OS and the Palm OS SDK 
provide a rich Loolkil for developers w ho want to or need to 
write international applications. Code Warrior Professional users 
who want to try out the Palm OS tools can do so after October 
by visiting lhe Metrowerks web site and downloading the tools. 

Users who want to play with the BaseX project file or the 
application can download the archive from the Metro werks 
Palm OS web site listed at the end of the article. 

Resources 

* http;//www.metm^ 

Metrowerks support site for Palm OS. Contains samples, FAQs, 
and utilities that aren’t on the CodeWairior tor Palm OS CD, 

* http://babelfish.altavista.com 

Provides web-based translation between various languages. 

* http://www.palm.com/devzone 

Palms' developer zone, 

* http://ls.palm.com 

A list server, maintained by Palm, where developers can ask 
questions about CodeWairior, conduits, Palm OS programming, 
and other relevant topics. RSTi 
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NETWORK 

MANAGEMENT 


By Alan B. Oppenheimer, Open Door Networks, Inc. 


The Service Location Protocol 


Making IP as easy to use 
as AppleTalk 


protocol. As with any new protocol, however, limitations and 
issues exist which will need to be addressed its the protocol, its 
implementations, and products that use it mature. 


Overview 

Due to the tremendous popularity of 
the Internet, Internet Protocol (TP) is rapidly 
Incoming the standard for communications 
over organizations* internal networks 
(intranets) as well as over die Internet itself. 
As Macintosh administrators migrate their 
traditionally AppleTalk networks to IP, they 
are discovering that much of the ease of use 
which their customers have previously taken 
for granted is txring lost. Unlike AppleTalk, 
IP was simply not designed witli a focus on 
the end user. Luckily an effort started nearly 
ten years ago by Apple Computer is finally 
starting to pay off and easy-to-use IP may be 
just around die comer. 

The Service Location Protocol (5LP) is 
an emerging Internet standard for 
automatic resource discovery on IP 
networks. Work on SLP, which brings 
AppleTalks point-and-dick service 
location features to IP networks, was 
initiated by Apple in die late 1980*5, As 
usual Apple was a bit ahead of its time, 
and the work progressed slowly for years. 
The recent explosion of interest in the 
Internet, coupled with the migration of 
internal networks to IP, has rekindled 
interest in the protocol 

Apple's recent inclusion of SIP as part 
of the new r Network Services Location 
(NSL) Manager in Mac OS 8,5 continues 
the momentum that is building behind the 


SLP Objectives 

According to the SLP specification (RFC 2165), SLP “provides 
a scalable framework for the discovery and selection of network 
services" and “eliminates the need for a user to know the name 
of a network host supporting a service.” Sound familiar? To those 
of m using AppleTalk and the Chooser for the past 14 years, 
another way of stating this objective is To enable the creation of 
a Chooser-like application that works with Internet rather than 
AppleTalk protocols.” 

An additional objective of SLP is to address AppleTalk’s 
limitations in the naming area. Specifically, AppleTalk naming 
services are viewed (correctly or not) as difficult to scale to large 
network environments. SLP attempts to overcome these limitations 
by allowing, buL not requiring, centralized name servers. 

SLP History 

As the Macintosh's naLive networking system, AppleTalk was 
designed with the Macintosh's principal focus in mind: the end 
user. Specifically, Apple built a dynamic naming and service 
location system into AppleTalk. Through the Name Binding 
Protocol (NBP), services could dynamically register on the 
network. And through the Macintosh Chooser and equivalent 
third-party functionality, such services could he browsed for and 
accessed through Macintosh-standard point-and-dick technology. 
Although originally just used for printers, the Chrxiser rapidly 
grew into the standard for finding and accessing other AppleTalk 
devices, such as AppleShare and compatible file servers. 

In the mid 1980s, due mainly to the Mac's success in 
university environments, Apple realized that a Macintosh 
implementation of the TCP/IP protocol suite was needed. 
TCP/IP, designed by and for the research community, had 
functionality and scalability as its principal goals and paid little 
attention to ease-ol-use. As Apple began implementing and 


Alan Oppenheimer is president and founder of Open Door Networks Inc., a Macintosh Internet tools and services company. 
Before founding Open Door in January 1995, Alan worked at Apple Computer for 11 years, where he w as one oi the creators 
of the AppleTalk network system. 
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distributing TCP/IP on the Macintosh (MacTCF), it concluded 
that the TCP/IP protocol suite would need to be enhanced to 
meet the overall case-of-use requirements of Macintosh users. 

In the late 1980s, Apple approached the Internet 
Engineering Task Force (IETF), the body responsible for 
developing Internet-standard protocols. A working group was 
begun on die subject of Finding services on IP networks, using 
the techniques developed in AppleTalk and NBP as a basis. 
Although the group made some progress, there did not seem to 
be enough interest in making IP easy to use, and the SLP effort 
moved very slowly. Ii is important to remember dial, at diat time, 
the domain name system (DNS) was just getting started, and no 
one had even heard of a URL. 

With the explosion of interest in the Internet and Internet 
protocols over die past few years, work on SLP has been 
reinvigorated, SLP version 2 has been proposed and a Service 
Location Web site has been established <http://WWW.SVrloc.org>, A 
number of vendors have implemented SLP and "connectathons” 
have taken place to test SLP implementations and enhance 
interoperability between vendors, Novell recently included an 
SLP implementation with NetWare version 5. In this area, things 
are accelerating rapidly, 

SLP Details 

SLP is based on concepts developed by Apple as part of the 
Name Binding Protocol (NBP) and the Zone Information 
Protocol (ZIP). In its simplest form (and the only form currently 


commercially available), SI.P uses the same distributed database 
ideas used in NBP, That is, a service, wishing to he available by 
name to clients on its IP internetwork (diat is, on its intranet), 
makes a call to its local SLP implementation. The service 
provides dial implementation (known as a Service Agent, or SA) 
with its URL and various of its attributes (such as its name and 
the fact that it's, for instance, a Web or AFP server). The SA stores 
the passed information in its portion of the distributed naming 
database, and is from that point on responsible for advertising 
the service on the network. Note that, unlike with NBP, the SA 
does not seem to confirm that the service’s name is unique on 
the network. 

A client application, wishing to obtain a list of available 
services of a particular type (or other attribute), calls its local SLP 
implementation (known as a User Agent, or UA). The UA is 
responsible for finding services of particular types by looking 
through the distributed database maintained by SA’s throughout 
the network. To look through the database, the UA sends (via a 
multicast address) a series of request packets, which are received 
by all the SA T s on the intranet. The requests contain details of die 
specific attributes of the service being looked for. Any SA that 
contains information in its portion of the database that matches 
the request responds direedy to die requesting UA with the 
information. In this way the UA can accumulate the desired 
information and pass that information back to its client. 

The above scheme is essentially identical to NBP’s, 
Additionally, both NBP and SLP contain provisions for looking 
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for services in a hierarchical fashion. In NRP, hierarchy is 
introduced through the concept of zones and die Zone 
Information Protocol. In SLR the equivalents of zones are called 
“scopes." Scopes allow services to be searched for within 
administrative domains, just as with zones. Unlike with zones, 
however, there is currently no specific protocol for maintaining 
scopes, which must be statically configured into various 
components of the system. 

An area where SLP tries to improve on NBP is through the 
optional use of centralizing name servers, called Directory 
Agents or DA's, DA’s eliminate the need for UA’s to send out 
multicast packets when looking for services. Multicast packets 
traverse entire intranets and can result in significant traffic in 
large network environments (although there are many people of 
die opinion that the significance of this traffic is quite overrated). 
In the presence of DAs, UA*s send lookup requests to their local 
DA, which maintains the list of all registered names within die 
DA’s scope. Multicast is not needed. The DA responds direedy 
to Lhe IJA. Similarly, SA’s send names which have been 
registered to their local DA t rather than maintaining those names 
in their pan of a distributed database. The address of the DA 
associated with any particular machine (SA or IJA) is obtained En 
much the same way as the machine's router or DNS, for instance 
through DHCP or static configuration, 

SLP responses SLP SLP 



SLP reqjest (mu It cast) 


Figure 1 . Service Location Protocol Operation 
(with and without Directory Agent) 


SLP and Mac OS 8.5 

When Apple shipped Mac OS 8.5, it brought the SLP effort it 
started nearly ten years earlier to fruition. Mac OS 8.5 includes the 
new Network Services Location (NSL) Manager, an API which 
enables services to register through protocols like SLP and client- 
side applications to browse for and initiate access to such services. 
NSL provides a plug-in architecture for service location, Mac OS 8,5 
includes an SLP version 1 plug-in, along with a plug-in that utilizes 
static DNS-based configuration. It is expected that Apple and third 
parties will provide additional plug-ins in die future. 

As with many of its early "enabling technologies,” Apple 
seems to be counting on third parties to utilize the NSL 
technology Lo provide end user solutions. The only use of NSL 
within Mac OS 8.5 itself is that Personal Web Sharing registers 
with the NSL Manager. Neither the Chooser nor the new 
Network Browser, nor Navigation Services utilize NSL to present 
a list of registered, services to ike end user. Additionally no end- 
user documentation discusses NSL or SLP in any way. The only 
information available is from Apple's developer Web site 


<http://developerapple,com/macos/8,5.html#nsl>, 

SLP Limitations 

Like any new technology, a number of limitations exist with 
SLP in its current state. Most of these limitations relate to the 
scalability of the system. SLP adopted many of the best features 
of AppleTalk, while at I he same time trying to improve upon 
AppleTalk's perceived limitations in large network 
environments. Many of SLFs scalability features, however, have 
not yet been fully implemented 

Jusl as AppleTalk defined die concept of a “zone", in which 
services could be searched for in a hierarchical manner, SLP 
defines the very similar concept of a “scope." Scopes, however, arc 
generally statically configured into servers, end nodes and, when 
available, Directory' Agents (DA’s). Due to this limitation, Apple 
chose to base scopes (called “neighborfuxxls” in NSL) on domain 
names in their Mac OS 8-5 implementation. Use of domain names 
for scoping creates various problems in intranet environments. For 
instance many intranets use only one domain name, without 
subdomains. Due to these current limitations wiLli scopes, many 
third party products, such as Open D(X>fs Share Way TR will be 
unable to take advantage of scoping, and will have to present 
services in a non-hierarchical list for the time being, 

SLP also attempted to mimic AppleTalk s ability lo provide 
dynamic naming services without need for any centralized name 
servers or other agents, SLP uses IP multicast for this purpose, just 
as N BP uses a zone-wide broadcast. As with zone wide broadcast, 
IP multicast requires the cooperation of IP routers, the devices 
which cotinect IP subnets together to form intranets, Most current 
IP routers implement IP multicast, which is used for such features 
as IP-based audio and video broadcasting and video conferencing. 
However IP multicasting may not be completely implemented 
across some intranets. In the absence of IP multicasting, SLP name 
lookups will only work within the subnet on which they are 
performed, or within Lhe groups of subnets over which IP multicast 
is supported. Additionally it appears that Apple's Mac OS 8.5 
implementation of SLP artificially limits the radius of any SLP 
search to three subnets from the initial requestor. 

In large environments. SLP attempts to improve upon NBP by 
optionally allowing centralizing Directory Agents, DA s minimize 
the need to use IP multicast, and can result in significantly less 
traffic than a completely distributed system like NBP. They can also 
enhance the protocol's hierarchical scope concept, and provide 
other services. Unfortunately, at ihc current time, no commercially 
supported DA is available, so IP multicast must continue to be 
used. As SLP momentum continues, however, it is expected that 
DA’s will }ye commercially available in the near future. 

An additional pn >blem wiLh SLP seems to be that it does not 
attempt to prevent duplicate name registration. In the dynamic 
environments which Macintosh users are used to, it is only a 
matter of time before this piece of NBP functionality is missed. 

As developers, vendors and users learn from SLP 
experience, changes to the .protocol will undoubtedly be. made 
Work is proceeding on SLP version 2. which enhances use of IP 
multicast to achieve greater efficiencies, addresses other 
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limitations and provides new features. SLP v2 is not yei 
commercially available however 

Despite its current limitations, SLP remains veiy useable for 
specific tasks, such as dynamic service location on all but the 
latest of intranets. Even within large intranets, SLP should function 
well for workgroup-spec ific service location. And as both Apple 
and third-parties enhance their implementations, most current 
limitations should soon lie eliminated, providing an IP service 
location system that Is just as easy to use as AppleTalk’s. 

SLP Fltures 

Trying to guess how anything related to Lite Internet is 
going to evolve is asking for trouble. Trying to guess how 
anything related Lo Apple and the Internet is going to evolve is 
asking for even more trouble. It seems likely, however, that 
Apple will integrate more and more SLP technology directly into 
the Mac: OS. Both the Network Browser and Navigation Services 
(the Standard Tile replacement) seem like natural places to 
integrate SLP browsing functionality. Both of these utilities can 
already browse AppleTalk-based servers through NBP, so 
browsing through SLP definitely seems like an appropriate next 
step. On the other hand, it appears as if these technologies are 
intended to eventually replace the Chooser, which has always 
been AppleTalk- and printer-centric, Thus SLP browsing may 
well not lie integrated into the Chooser. 

It would also be a relatively trivial matter for Web browsers 
and FTP and other Internet clients to add support for SLP 


browsing, in much the same way as Open Door added such 
support to ATP Engage! With SLP now built into the Mac OS. we 
could quickly see the appearance of application-specific 
browsers. A chicken-and-egg issue exists with this scenario 
however. Client application developers want servers to use SLP 
before they add SLP support, and server developers want clients 
to do the same. One of the reasons Apple built SLP registration 
into Mac OS 8, Vs Personal Web Sharing, and one of the reasons 
Open Door is pushing the technology, to is to get around this 
ch ieken-and-egg pre >ble i n. 

Other NSL plug-ins may also come to market, either from 
Apple or third parties. In particular, Lhc Lightweight Directory 
Access Protocol (LDAP) is becoming popular in certain 
environments, and could be used as the basis of various service 
location schemes, although additional work would lx needed 
on how to use directories for service location. Gateways 
between SLP and LDAP are also envisioned. 

Another area for potential future development is SLP proxies. 
Envisioned by the SLP specification, an SLP proxy Ls a device that 
registers (arts as a User Agent) For another device Unit cannot do so. 
Through SLP proxies, SLP support am be added to legacy devices 
that don’t support SLP, such as printers and older Wd) servers. 
Finally, SLP includes a rich set of features which are currently not 
being taken advantage of, such as the ability to associate any 
numlxT of attributes with any device, and to search by attribute* It 
is very much hoped that we see implementation and use of these 
advanced features in Lite near future. 
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Summary 

After a number of years of inattention, Apple's effort to 
bring AppleTalk's ease-of-use to Internet protocols is beginning 
to pay off. The Service Location Protocol shows promise for 
providing a much-needed means of dynamically browsing for 
and selecting services in intranet environments. As with most 
new protocols, limitations and issues remain, and third parly 
implementations are scarce, but the inclusion of SLP in Mac OS 
8,5, coupled with efforts such as Open Door’s Share Way IP 2.0 
should serve to further enhance the momentum behind SLP 
and lead to a much easier to use Internet, 

SLP in Open Door's ShareWay IP and AFP Engage! 

2,0 Products 

Open Door Networks has accepted Apple's challenge 
and ts providing the first end-user products to lake advantage 
of NSL and SLR Open Door's president (and author of this 
article) Alan Oppenheimer was involved in both the design 
of AppleTalk and Apples initial SIP efforts, Open Door's 
ShareWay IP 2.0 product (sec sidebar), which provides 
AppleTalk Filing Protocol (AFP) file service using IP 
protocols, registers with NSL to make itself visible through 
SLR And Open Door s AFP Engage! 2.0 product acts as a 
“Chooser" for SLP-registered AFP servers, displaying a 
dynamically updating, browseable list from which users can 
select the server they wish to initiate access to. Through 
Open Door's ShareWay product family and SLP, Macintosh 
file sharing services, including Personal File Sharing, become 
as easy to use over IP as over AppleTalk. 

When Apple told us about SLR it became clear that 
ShareWay IP (figure 2) was a perfect product to which to add 
SLP functionality, the product provides any AppleTalk-based 
AFP server with the ability to deliver AFP file service over IP. 
Although best known for Its ability to add IP capabilities to 
Lhe Mac's built-in personal file sharing, ShareWay IP also lets 
older versions of AppleShare, Windows NT. Novell NetWare 
and Unix AFP servers provide IP-based service, 

ShareWay IP 2.0 uses SLP to register the URL to ils 
targeted server on the network. Since Apple’s 
implementation is somewhat limited in terms of its support 
for SLP attributes, ShareWay IP includes all the relevant 
attributes in lhe UHL registered. Specifically, the UHL 
registered is of the form: 

• afp://IP-addr8SS/?MAME=TargetMachineNameSZONE^ZoneName 

* IP-address is the IP address of the ShareWay IP machine 

* TargetMachineName is the Larger server’s machine name 

• ZoncName is the name of the AppleTalk zone, if any, in 
which the largei server resides 

As we began to investigate Apple’s SLP implementation, it 
also became dear to us that we were going to have to write a 
dien t-s i d e b r<) vv ser a p pl i cal i on .—De.sp i te the ob v * on s 


opportunities for integrating SLP with both the Chooser and 
the new Network Browser {let alone Navigation Services), 
Apple's 8.5 implementation provides no client-side application 
for browsing SLP-registered services. Although wc expect 
Apple to provide such integration in the future, we didn't want 
to wait for what could t>e an indeterminate amount of time. 
We also already have a somewhat appropriate client-side 
application. Our AFP Engage! product had been serving as a 
helper app for AFP URLs for over a year, enabling users to 
click on AFP LJRLs in Web browsers, email readers and other 
Internet applications. The addition of an SLP browser for AFP 
servers thus seemed like a natural addition. 



Figure 2. Browsing IF-based AFP sewers using 
SLP and AFP Engage! 

AFP Engage! 2.0 includes a new, Chooser-like window 
(figure 2) that lists all SLP-registered AFP servers, AFP 
Engage! simply calls the NSL Manager to obtain a list of any 
servers registered with AFP URLs, and displays the associated 
names of those servers in the window, When the user 
double-clicks on one of the servers, AFP Engage! calls the 
AppleShare client to mount the associated server, just as it 
has done previously for AFP URLs, Due to limitations In 
Apple's implementation of SLP scopes, scoping is ignored by 
both ShareWay IP and AFP Engage!, and servers are 
displayed in a single, non hierarchical list. We expect to add 
scoping in the future. 

The combination of ShareWay IP 2,0 and AFP Engage! 
2.0 thus serve to provide AppleTalk-like ease-of-use for 
Share Way-supported AFP servers, in fan, with AFP Engage's 
ability to process AFP URLs, the combination provides a 
solution which in some ways is even more flexible than 
AppleTalk's — users can access servers either the AppleTalk 
way, through dynamic browsing and poim-and-click, or the 
IP way, through URLs. 

Open Door is hopeful that these two products are just a 
start, and that we sec such ease-of-use and flexibility added 
over time to more and more network products. Apple has set 
the stage. Now it's time for both third parties and end users 
tOnSta rt acting! -—- B 
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Presenting a Baker's Dozen 
of Different Ways To Make 
Your Web Site Better 


1. Manage Web crawlers to improve your search 
rankings and thwart spam. 

2. Customize pages for Windows, Mac, and Unix 
visitors. 

3- Add page counters and track clicks on links to 
off-site URLs. 

4. Foster a community with a Web-based bulletin 
board system. 

5. Insert banners into pages and administer them 
via the Web. 

6. Accept orders for products, information or 
anything else on-line. 

7. Publish a newsletter, without teaching HTML 
to your contributors. 

8. Run exams, quizzes, and surveys with instant 
grading and results. 

9. Automate subscriptions and archiving of your 
mailing lists. 

Help visitors navigate your site with “Jump 
Pop-Ups.” 

11. Create visitor-specific “Preferences” for surfing 
your site. 

12. Improve error handling and get notified about 
bad links on your site. 

13. Keep your site fresh by making it easy 
to update your pages with news and | 
timely content. 


NetCloak 3.0 Professional makes all this (and much 
more) easier than you think. Check it out at: 

http://examples.maxum.com/ 







PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Westford\ MA 


SupebDuperGhost 

This month we’re going to play a word game. One derived 
from a game called GHOST The basic concept Ls simple - players 
spell a word, taking turns adding letters to die growing word, 
trying to avoid being the player who says the last letter of the word. 

To start, one player says a letter. The next player thinks of 
(bur does nor reveal) a word that logins with the given letter, 
and then announces the first two letters of that word. The next 
player thinks of a (possibly different) word that starts with die 
first two letters, and announces the first three letters of that word. 
Play continues until a player spells an entire word that is more 
dmn three letters long. The player who completes the word loses 
the round. If a player spells a string that is not part of a real 
word, that player loses the round. 

A game with three players might go like this: 

Adam: [thinking of "toast"]: T 

Betsy: [thinking of "tadpole"]: TA 

Cynthia: [thinking of "tatting"]: TAT Iwhich with three letters does 
not count as a wordl 

Adam: (now thinking of "tattoo, 11 since "tadpole" no longer fits 
the current string of letters]: TATT 
Betsy: [also thinking of “tattoo"}: TATTO 
Cynthia: [has two options: finish the word “tattoo" and lose 
this round, or spell a nonexistent word, and also 
lose. She resigns! 

In our game, there are a few variations. Instead of always 
adding a letter to the end of the string, well also play games 
where you can only add to the beginning, games where you 
can add to the beginning or to the end, and games where you 
can add a letter anywhere. Our games will also be restricted 
to two players, wiLh each Challenge contestant competing 
against each other contestant. 


The prototype for the code you should write is: 

#if definedE_cplusplus) 

extern "C” I 
fold if 

typedef enum 1 

addToEndOnly “ 0, 
addToBeginningGnly, 
addToBeginningOrEnd, 
addAnywhere 
1 GanieType: 

void InitSuperDuperGhosU 

const cha t MictWocds [] ,P alptutxiicdh sorted uppercase dictionary words 7 
long numDic cionaryWords P number of ruiIHamitwtcd words in dictionary 7 

I; 

void NewGhostGame{ 

GameType the&ameType 

); 

void PlayGhostt 

const cha r * gbostSt ring, /* die siring so far, null-termmated 7 

cha r newChos t S t ring [256J, p new glwstString, one letter added to gJinstString 7 

int 'wordlnMindlndex. 

r your siring will match dictWoidsJwordlnfttindlndex] 7 

int charPosition#[25f>3 * 

P index into dkfWrcfc|wixdlnMindlixlex| for cadi dw in newGImSiring 7 

h 

void TermSuperDuperGhost(void); 

fjlf defined(_cplusplus) 

I 

fold if 

The vocabulary for our game consists of numDictionaryWords 
alphabetically sorted uppercase words provided to your 
InitSuperOuperGhost routine in the dictWords parameter The 
dictionary will typically consist of 40000-50000 words but will 
never exceed 100000 words. All dictWords will be greater than 3 
letters in length. InitSuperOuperGhost should analyze the dictionary 
and create intermediate tables if appropriate* At the end of the 
contest, TermSuperDupcrGhost will !>e called, where you should 
deallocate any dynamic memory allocated by InitSuperOuperGhost 


THE RULE5 


Here's how it works; each month we present a new programming 
challenge. First, write some code that solves the challenge. Second, optimize 
your code (a lot). Then, submji your solution to MacTech Magazine. We 
choose a winner based on code correctness, speed, size, and elegance (in 
that order of importance) as well as the submission date. In the event of 
multiple equally desirable solutions, well choose one winner (with 
honorable mention, but no prize, given to the runner up), The prize for each 
month's best solution is a $100 credit for Developer Depot™. 

Unless stated otherwise in the prolAmi statement, die following rules apply: 
All solutions must be in ANSI compatible C or C++, or in Pascal. We disqualify 
entries with any assembly in ihem (except for challenges specifically suiting 
otherwise ) You may call any Macintosh Toolbox routine (e,g. r it doesn't owner if 
you use Newftr instead ofmalkxi We compile all entnes into native PowerPC 
ctxk with compiler options set to enable all available speed optimizations. The 
development environmem to lx used for selecting lbe winner will be slated in the 
problem, limit your code to 60 characters per line or compress and binhex the 


solution; this helps with e-mail gateways and page laymit. 

We publish the solution and winners for each month's Programmer's 
Challenge three months later. Ail submissions must lx received by the 1st day 
of the month primed on die front cover of this Issue. 

You can get a head start on the Challenge by reading the Programmer's 
Challenge mailing list. It w ill lx* posted to the list on or before the 12th of the 
preceding month. To join, send an email to ILstserv®ILstmail.xpbin.com with 
the subject “subscribe challenge-A*. 

Mark solutions “Attn; Programmer's Challenge Solution" and send it by 
e-mail to one of the Programmer's Challenge addresses in the “How to 
Communicate With Us 1 * section on page 2 of this issue. Include the solution, 
al related files, and your contact info. _ 

MacTech Magazine reserves the right to publish any solution entered in 
the Programmer's Challenge, Authors grant MacTech Magazine the exclusive 
right to publish entries without limitation upon submission of each entry. 
Authors retain copyrights for die code. 
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Each round will consist of each Challenge entry competing 
against each other entry in a game of each GameType, once 
playing first and once playing second. Each player will be 
notified of die start of a new game with a call to NewGhostGame. 
At each aim, a player's PlayGhost routine will be called. The 
null-terminated ghostString parameter will provide the string 
played thus far in the game, which is guaranteed to be part of 
some word in dicfWords, The PlayGhost routine must add a single 
character to the ghostString, at the beginning, the end, or 
anywhere, depending on theGameType parameter to this game, 
and return the result in newGhostString. PlayGhost must return 
in wordlnMindlndex the index into dictWords of the word matched 
by newGhosLString, To help the rest program evaluate your 
move, you must also set the charPositions array, so that: 

newGbostStringfil * 

dictWordsfvordlnMindlnde^] [cbarPcisitioneliJ j 

Hie winner of each game wins 100 points, bach player's 
score is reduced by 1 point for each 10 milliseconds of execution 
time, including the time taken by the initialization and 
termination routines. The Challenge winner will be the player 
with the most points at the end of the tournament, 

if you cannot add a letter to the ghostString without forming 
a word, you should return a null string in newGhostString, 
Alternatively, if you form a word in dictWords but return a non- 
null string, you will lie penalized 50 points. 

Tliis month's Challenge was suggested by JG Heithcock, 
who wins 2 Challenge points for the suggestion, if you have an 
idea chat you think would make a good Challenge problem, 
send it to <progchallenge@mactech,conn> for passible consideration 
in a future Challenge. 

This will he a native PowerPC Challenge, using the 
Code Warrior Pro 5 environment. Solutions may l>e coded in C, 
C++, or Pascal. Solutions in Java will also lie accepted this 
month. Java entries must lx: accompanied by a test driver that 
uses the interface provided in the problem statement. 

Three Months Ago Winner 

It seemed like a simple Challenge when I wrote it. The July 
C-to-HTML Challenge, that is. Write some code to convert a valid 
C/C++ file into HTML, so that die Jitml file displays in Netscape 
Navigator the same way die x, xp, or.h file is displayed by the 
Code Warrior (Pro 4) IDE. A simple matter of syntax coloring, right? 

Well, yes, but it wasn't quite that simple. First, there is the 
question of #pragma and other preprocessor directives. The list 
of which directives CodeWarrior recognizes requires a little 
research and experimentation. Second, the treatment of 
#pragmas and other proprocessor directives is something less 
than consistent in CodeWarrior Pro 4. For example, consider the 
ft) 11 ow ing directives: 

tfident 

/jfpna^ma options ali&n=mac68k 
#pragma ANSI strict 
#pragma reaiater_celoring 
_declspec(export) 

_dec Is pec {import) // notice imptm is noi hiHghicd 


Of that list, “tident" is recognized but not colored, “options'* 
is colored but 'align=mac68k" is not, u ANSI_stricf (and most other 
#pragma directives) is colored, but “tegister.coloring” (and another 

.set of directives) is not. The '“export" argument in a _declspec 

command Is highlighted, but import" Ls not. Go figure. 

Then there was the question of line continuations. The 
CodeWarrior IDE doesn't color an include file as a string when it 
is written on one line: 

^include "stdlib.h" 

... but it does color it if the include is broken into two lines 
with a line continuation character. 

^include \ 

“stdiib.h- 

And proprocessor directives broken with line continuations 
are colored based on what the fragment looks like. In the 
following examples, "if” is colored in both places, but die rest of 
the directive is not Go figure some more. 

#if\ 
def K 

#def\ 
ine L 

if 

Other inputs that tripped some people up: 

#include “CtoV 

HTML. h" r note die unmaidicd quotes {“) here, one is black, ilic other grayfV 
long q**7/st'; 
long r*T-* ‘ t 
long ,,V*: 

The proprocessor coloring confusion probably turned ofF some 
potential contestants, but, if dial were not enough, there was die 
issue of proportional fonts. The original problem statement required 
that lab diameters be processed correctly, including spacing when 
using proportional fonts. ThaL turns out to be rather difficult in htnii, 
so, alter some discussion on the Challenge mailing list, I decided to 
test with monospaced fonts only. 

Speaking of the mailing list, if you are not already on it, I 
would encourage you to join. Not only does it give you more time 
to solve the Challenge (problems are sent out on or around the 12th 
of die preceding month), hut you can also tune in to any problem 
clarifications. See <http;//www.mactechxom/pmgchallenge> for 
subscription instructions. 

So, after that long introduction, congratulations ONCE 
AGAIN to Ernst Munter (Kanata, Ontario) for submitting die 
fastest and most correct solution to the C-to-HTML Challenge. 
This is Ernst’s third Challenge win in a row - is diere no one out 
there ready to mount a serious Challenge to his outstanding 
record?! Ernst and two of the other participants took advantage 
of the <SPAN> HTML mg and other Cascading Style Sheet 
properties in converting code for display in a browser. Ernst 
parses the text using a state machine and six tables, defined in 
the HTMLcodes structure, based on whether the state 
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corresponds to leading white space, intervening white space, 
preprocessor lines, strings, C-style comments, or C++-style 
comments. Text coloring is done using style sheets. Ernst’s code 
converts the familiar "Hello World” program from: 

r 

* Hello Wurid for the QxkWarrtof 

* i W74<m Metrowertts Corp 

* 

* Questions and comments to: 

* cmaUioisupport &mc irowcrbxotn> 

* <hrtp://www. metro wefts. tom/> 

7 

ffinclude (stdio.h) 

■(/include (stdiib.h) 

//include <time,h> 

int main(void) 

t 

printf ("Hello World, this is CodeWfirrior I \n\n“); 
return 0 : 

\ 


,.. into: 

<!LX)CTYPE HTML PUBLIC * //W 5 GYDTD Him 4 . 0 //EN' 
**http://www,w 3 ,org/TR/REC j htntl 40 /lot>se,dt<l w > 

<htal><head>(STYLE nrF-"text/css H > 

<!- 

pre t colorixOQOOOQ: font: 9 pt 

tnonaco J #p(color:black 3 #c(color:xccOOOO1#kI color: JtOOOOcc1JsIcolo 
r:* 77777 H-> 

(/STYLEX/headXbody bgcolnr-^FFFFFF") 

<pre> 

(SPAN ID“ H c“>/* 

* Hello World for the CodeWarrior 

* 60169 : 1997 - 199 S Netrowerks Corp. 

* 

* Questions and comments to: 

&#Q6Q: cuailto: support &metrowerks.cora&#Q62 : 

1 &#060: htt p:7 /www * me t rowerks. con/&#06.2: 

*/</SPAN> 


Top Contestants 

Listed here are the Top Contestants for the Programmer's 
Challenge, int ]tiding everyone who has accumulated 10 or more 
points during the past two years. The numbers below include 
points awarded over the 2 1 most recent contests, including 
points earned by this month's entrants. 


Rank 

Name Paints 

Rank 

Name 

Points 

TT 

Munter, Ernst 

221 

11. 

Mai ten, Jeff 

20 

2. 

Saxton, Tom 

108 

12. 

Nicolle, Ludovie 

20 


Boring, Kandy 

73 

13. 

Murphy, ACC 

14 

4. 

Maurer, Sebastian 

70 

14. 

Shearer, Rob 

14 

5. 

Rieken, Willeke 

51 

15. 

Hart, Alan 

11 

6. 

Heithcoek, JG 

39 

16. 

Hewetl, Kevin 

10 

7. 

Lewis, Peter 

26 

17. 

Selengut, Jared 

10 

8. 

Jones, Dennis 

22 

18. 

Smith, Brad 

10 

9. 

Brown, Pat 

20 

19. 

Varilly, Patrick 

10 

10. 

Hostetfer, Mat 

20 





There are three ways to earn points: (1) scoring in ihe top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) f>eing the first person to 
suggest a Challenge that I use. Ihe points you can win are: 


1st place 

20 fXiinus 

2nd place 

10 points 

3rd place 

7 points 

4th place 

4 points 

5th place 

2 jx)ints 

finding bug 

2 points 

suggesting Challenge 

2 points 


(SPAN ID-“k">#include< / SPAN> &jfG60:stdio,Hto2: 

(SPAN H>="k">fliuciude<7SFAN> &#0M;stdHb.hAi#O62; 

(SPAN I>#inc Iude< / SPAN) A#060: t j.mc.h&*062 ; 

(SPAN IB-"k w >int</SFAN> ftalnKSPAN ID="k tt >void</SPAN>) 

t 

printf ((SPAN IlK^-ftiUo World, this U 
CodeWarriar!\n\ir</SPAN>); 

(SPAN rD-"k">return</SPAN> 0: 

1 

</pruX/bodyX/hmL> 


Fortunately, the quirks of the IDE did noi affect the results, as 
the solutions ranked the same when ordered by execution time as 
they did by correctness. The table below lists, for each of die 
solutions submitted, the total execution Lime, a correctness rank, 
and the size and language code parameters. As usual, the number 
in parentheses after the entrant s name is the total number of 
Challenge points earned in all Challenges prior to this one. 


Here is Ernsts winning C-toHTML solution: 

c2htmLcp 

Copyright © 1999 

Ernst Munter, Kanata, ON, Canada 

r 

Submission to MacTcch Programmer s challenge for July 99. 

Copyright © 1999, Ernst Mwucr. Katya ON Canada. 

x<o\rmv 

Problem Statement 

Convert a syntactically correct C or C++ tm tile into an HTML Lite such that Netscape 
4.6 displays the text in the same way as die Code warrior Pro4 editor. 

Settings provide dynamic control of tout and colors. 

Issues 

There are three kinds of issues 


Name 

lime 

Correctness 

Code 

Data 

LanK 


(msec) 


Si;re 

Size 


Ernst Munter (4&7) 

22.31 

1 

4128 

(W88 

C++ 

Dennis Tune* M2) 

4176 

1 

4778 

7404 

r 


Yudhi Wiftyatimia 

71.40 

3 

4292 

59S5 

C++ 

Alan Han (21) 

1863 09 

4 

4788 

4099 

C 


- CW coforizatiofl of keyword* and strings does nm always match the semantics of 
the text, for example not all preprocessor keywords arc displayed in keyword color, 
and comments and line continuations affect keyword and string colors in 
preprocessor statements. Although this behaviour of the CW editor is inconsistent 
with the behavior of the compiler, it is predictable, and should be emulated here. 


I tTML provides no direct way to provide tab stops (beyond line indentation). Only 
monospaced fonts display property when tabs are replaced with equivalent numbers 
of space characters. 
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TIlC Apple character set contain 4 number of characters not available in I ITML 
fouls. Qtaiion ami insert ton of small Images might solve this problem, but 1 consider 
this beyond the scope of this Programmers Challenge 

Solution 

Tlie <pre> and <span> tags, together with a few CSS styles are used to control the 
font and colors in the HTML output 

The parsing of the input text character by character is based on a table driven stale 
machine, Six tables, largely identical hut differing in a few key areas, are prohibit lor 
the six major states which the text cart be in: 

-Text ant! white space after a newline 
Test after the first (not *) character on a line 
Preprocessor lines 

■ Strings (except in include and pragma preprocessor lines) 

- C style comments 
* C++ style commons 

A loop ln TextCoaverter:CorvcrtTcxtO then simply looks up each input character in 
the current table, and processes it. This involves scanning ahead to find keywords, 
and, as triggered by context (table) specific characters, the selection of a different 
table. 

Tabs arc expanded using a small table of tabstops. 

Display colors arc controlled by cnebwing non black text with pairs of<5PAN ID=V> 
and </SPAN> tags, where x is the name in the style sited tor the desired colon 

Assumptions 


Lines ate not more than 255 character positions long. 
Tab stops beyond position 255 are ignored. 

All C/C++ files use Mac line ends (thcOD) 

Please turn 

^define MULTI_PUTR)RM 

UN if DOS type files types are to be processed. 


The eharaetCT bxl A (cnd-of-texi) will he so interpreted 
Compiler Settings (Please note) 


ItK- shortest and fittest code is obtained by setting the following compiler 
optimizations; 

- global optimization: level -1, faster execution speed 

- Processor Schedule instructions, Peephole optimization 
Language Inline depth = 5 or more 

With these settings, the program should be about 41,56 bytes of code and alx>ut HK of 

data 

7 

#defitie MULTI_PLATFGRM 0 

#i tie luck <cnrdio> 

^include "CtoHTML.IT 
tfimclude "keywords.h" 
include “HTKLBtrings.h" 

Open Page 

static char* GpenPage{ 
char* outputHTML. 
const Settings displaysfittings) 
l 

// Sends the preamble of the HTML page, 

return outputHTML + 

std::sprintf{outputHTML♦ 

M, is Vipt %s 1 #p! color; block I tfc I color: x*06x \fk I color; x%0bx I \ 

#3{color;x%Q6x)%s’\ 

kHcadl. 

displaySortirtgs, fontSize, 
display Set t ings. fcmtNante* 
display Set tings. c. omtnent Color. 
displaySettings.keywordColor T 
displaySettings.st rlngColor, 
kHead2 ); 

I 


Introducing... 


_ versionJ 

Funnel 





Funnel Web’s innovative design and 
powerful feature set helps make sense 
ot complex Web sites by identifying 
key trends and events. 

Features 

• point and click interface 

• over 50 reports and graphs 

• up to 50 times faster than 
major competitors 

• platform independent 

• works with any web server 
on the planet 

Advanced Technology 

• Event Messaging 

• Remote Administration 

• Realtime Monitoring 


Intelligent Web Monitoring and Analysis 


Accuracy, speed, ease of use and powerful report-formatting 
capabilities, makes Funnel Web the perfect solution for 
monitoring e-commerce, Intranet and Internet sites. 

Backed by Active Concepts unrivalled 24 hour technical support. 


Download a free demo version at 

http://www.activeconcepts.com 

or visit our website to find out more 
about the killer Funnel Web Spider... 











Close Rage 

static char’ ClosePage(char* outputHTML) 

// Close* tin: HTML page. 

// Noi strictly necessary but good form 
return outputHTML + 

etd; ;spriiuf(autputHTML, M %sM5Teil}; 


Static unsigned char gTabs[256]; 
static char spaces[260] = 


MakcTabsAmy 

static void MafccTabsArray(int tabSlza) 

if (iabSiae<l} tabSize-i; 
tahSize 4= GxFF; 
int c^tabSize: 
for (int i®0; 1(256 1 1-H-) 

I 

gTabsri]“c-; 
if <c< ip ^b) c'nabSize; 

) 

i 

enum I //state of HTML output 
kHTKLplain, 
kHTMLconacent, 
kHTMLkeyword, 
kHTMLslring 
I; 

#if macintosh 

// Mol a very nice technique, hut it works and is efficient 
// Lach 4 characters can be specified and copied as a long 

static long ospani= , <SPA i : 

static long ospanZ^N ID 4 : 

static char ©span}- 4 **: 

static long ospan^fM " •"*£*>*, 

static long cspmi“*</SP 4 ; 
static long cspan2"*AN> '; 

#else 

// conventional platform Independent C code 

static char* kOpenSpanfl = I 

"(SPAN 

"(SPAN ID~\"c\ M >“* 

“(SPAN U>V*k\*>\ 

44 <5FAN ID 
I: 

static char* kCloseSpan “ “(/SPAN)’ 4 : 

static int kCloseSpanLength - Gtrlcn(kCloeeSpan): 

static int kOpenSpanLength " strlen(kDpenSpan[0]); 

fendif 

// Make keyword lookup functions available 

static Keywords K: 

st run TcxtConvcrtcr [ i'l'M Let *ks 
//TextCon verier inherits context tables from UTM Ixodes 
// U is simply a collection off most functions so diev are 
// easily inlincd. 

static struct TextConverter;KTMLcodes f 
void CloeeSpan(char* & otitputHTML) 

// Returns the HTML fftatc^o-plahv {black fitters) 


#lf macintosh 

* (Clong‘)oui:putHTKL} = cspanl; 

4 ((long*)(outputHTML+A)} espau2: 
outputHTHL += 7: 

(else 

at rcpy(out pu t HTML,kCloseSpan); 
outputfiTML += kCioseSpanLength: 
ffendif 


void l?periSpan(char* h out put HTML. const int newHTMLstate) 

// Sets die HTML state to the desired color state 

(if macintosh 

*((long*}outputHTML) - ospanl; 

* ((long*) (outputHTML+'j)) = ospati2; 

*((char*)(outputHTMLifl)) ” OSpani; 

* ((long*) (outputHm+9)) - wpatri [newHTMLstatel; 
OtitputHTML <= 13* 

fjfelse 

strepy (output HTML. kOperiSpan[newHTMLatate]); 
outpurHTML kCpenSpanLength: 

fend \ f 

\ 

bool IsLiteral(const char* inputText) 

if Cheeks whether a “ is pan of a character literal 

return 

UnputTexl fl] «=* 4 \*‘) S.& 

( 

(inputText[-1] == 4 \ 4i J I 

( 

(inputText [ 1] ™ ' U'l && 

(inputText [ 2] = 4 \ 4, J 

) i 

1 

void SendNewline[ 
const char c* 
const char* & inputText* 
char* & outpuillTML) 

I 

// on emry,r= \n' and TuputTcxt is the next character 
// mums with "inputText - next unprocessed character 

fit HULTI.PLATFGFJI 

// this enables it for Mac, UNIX and DOS newlines 

if (7=(c A inputText[1J)) //skip OxA after I>\1) 

I l inputText; 

i?«nd i f 

*QULpUtUTKL++ = c; 


void SendTab (char * 4 out puLllTHL, int 4 Ipos) 

int ntifcSpac es “gTabs [ GxFF 4 iposj: 

Ipos += numSpaces; 
for t int 1^0:i<rumiSpaces:iHj 
'outputHTML-H- - * 1 : 


void SendPlainC 
char c, 

const char* 4 InputText* 
int len* 

char 4 4 outputHTML* 
int 6 Ipos} 

// Plain text b neither a keyword, nor contains any trigger 
if characters, our characters that need to lx- HTML encoded. 

4 outputRTHT J ++ - c:lpoe++: 
for (int i-I:i<Ien;i++) 

I 

e^'-H-inputText: 
if £c— 4 \t') 

SendTab(outputHTML*Ipos)r 
else I‘outputHTML++ * c:lpos++;l 
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void SendKeywordsf 
char c, 

const char* & inputText. 

Int len. 

char* k outputHTML* 
ini k Ipoa) 

I 

// Sends one ur marc consecutive keywords in keyword color 
OpenSpan(outpu L HTML,kHTMLkeyward): 

*outputHTML++ » c:lpoG++: 
for (int i-m<ien;i++) 

I 

e=*++inputText; 
if (e*“*\t*) 

SendTab(outputHTML,Ipos )i 
else f 4 uulpm HTML^ =c;lpos++;| 

I 

GloseSpan(outputHTML); 

I 

int GeiToken(const char* inputText) 

// Returns the length of 2 word, a potential keyword 

I 

const char* ep-inputText-1; 

while [cmapL(int)(unsigned char) (*-H-cp) J h word) 
f* impossible to avoid compiler warning here 7 ; 

// (no -pragma will do it) 

return cp-inputText; 

I 

int PragmaValue(const char* inputText) 

// Returns die length of the whitespace + keyword, of 0 
I 

char c; 
int Ten; 

const char * cp^inputText; 
while (0 I- (c = *++cp)) ( 

if (0 “ [c*aptlint) [unsigned char He)] h wup)) 

I 

len=GetTukeii(cfd: 
if (Un) 
i 

if (K,IsPragmaValuc(cp,1en)) 
return len + cp-inputText; 

\ 

breaks 

1 

I 

return 0; 

I 

int PrajpopDirective(coast char* inputText) 

// returns the length of the whitespace + keywords, or 0 

( 

char c; 
int len; 

const char* Cp^inputTexl; 
while (0 I- (c = *“H-cp)) I 

if (0 ™ CcmapUint) (unsigned rharHc)! k wsp)) 

i 

len=GctToken(cp); 
if (len) 

I 

if (K.IsPragmnUireeflve(cp.len)) 
return Pr*gmaVulue(cp+len) 

+ Cp + len inputText; 

) 

break; 

I 

J 

return 0; 

I 

lot Preprocessor(const char" inputText.int & PPstate) 
I 

// Scans ahead to determine the preprocessor keywords. 

// Returns the length of the string from tiic utitiai # 10 
// the end of the last colored keyword (or 0 if none found). 

// Emulates the CW Pro-4 editor bug where legal comments 
// between ~ and the keywords spoil colodaUJon of the 
// preprocessor keywords. 


Quadrivio General Edit 


Debug & Analyze 
Complex File Formats. 


(3)- 

m- 


□ = umm-0 \ 


-m 


1) Define your formal with familiar* (Mike statements. 

2) View, analyze, and edit data file in up to 5 columns. 

3) View and edit file parameters. Also edit handle blocks 

and other data structures in memory. 


Free! 

Lire & d«im* tetiiuiu 
available ivn wrb silt 


%f Quick insight into darn structure cot He tits. 

1 / Easier than studying MPWs dumpflle output. 
✓ Faster debugging with dear display of data. 
Saves coding time with direct data editing. 


Visit our web site for immediate download. 

On-line ($395) and boxed ($249) versions available. 
Also available from Developer Depot & SdTech Intern a tional. 


http://www.quadrivio.com 


Quadrivio Corporation info@quadrivio.com 
1563 Solano Avenue #360 Berkeley, CA 94707 [510)524-3246 


char c; //skip 1 # 1 
int len: 

const char* cp=iupuLTcxt; 
while (0 1= (c ~ *++cp)J l 

If (0 — temapl (int) (unsigned char> Ce) J & wsp )) 

I 

1en“GetToken{cp); 

if {len} 

I 

PPstate » 

K.IsPreprocesaorKcyvord(cp,len}; 
switch (PPstate) 
l 

case kPPepoiled: return 0; 

case kFPsimplc: 

case kFPinclude: return cp + len - inputText; 

case kPPpragiiia; return PragmaDireeiivetcp+len) 

+ cp + len inputText; 

I 

I 

break; 

I 

I 

return 0; 
i 

Int Get Plaintext(const char* inputText) 

( 

// Scans ahead to determine a section of text which may Iw 
// whitespace and punctuation, but no strings, literals. 

// comments, or newlines, nor cncodablc chars (<&>) 

// Returns Hie length of the section 

char e; 

c 0 net char* c p=in p uxText-1: 
while (0 E= [c ~ *++cp]) l 
if (0 — 

{cmap[(int){unsigned char1(c)] & nokey)) 
break; 
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I 

return cp-inputText: 

Int Get Key words( const char* inputText.int ft plain) 

// Scans ahead to determine 4 sequence of basic keywords. 

// Returns the length of die string to the end of the last 
// colored keyword (or 0 if none found). 

//The variable plain provides the number of characters 
// after the last recognized keyword, including a non keyword 
// and all white space and punctuation up to (excluding) the 
// next siring, literal, comment, or newline 

char c; 

lot len.aec - 0; 
plain “ 0; 

const char* cp - inputText*1; 
while (0 I" (c ** *++cp)) I 

if (0 = Ccmap[ (int) (unsigned char) (c) ] & wsp)) 

t 

1 e n*=Get Token (cp); 

if (len && K.IsBasicKeyword£cp f len)) 
cp += len* 

ace * cp InputText: 

cp-t 

I 

else 

t 

plain - len + GetPlaintext(cp+len) ; 
break: 

) 

\ 

I 

return ncc; 

I 

char* ConvertText( 

const char 4 InputText, 
char •outputHTML) 

// Loops over all input diameters, and determines text 
// states such as 

// - start (if a new line of plain text 
// - preprocessor activation 
// plain text after the first pin ting character 
// - “strings'" 

// ■ C C style comments 7 
// - // C++ style comments 
// - literals’ (no separate table) 

// 

// Hath character is looked up in a table associated with 
// the current slate. These tahles provide the triggers 
ft for state changes, When a state change occurs, the 
ft appropriate table is assigned. 
ft 

ft Potential keywords arc delected by scanning ahead when 
//this makes sense, so colorimiun can be applied for 
ft these keywords without backtracking in the output 

1 

char c: 

-inputText: 

const unsigned char* table=starTlndex: 
const unsigned char* returnTable=startTndex; 
int 1pos“Q.PPstate * plain >len,quoteCounter: 
for Ui) t 

c^'-H-inputText; 
evaluate: 

int code “ tablef[int)(unsigned char)(c)l; 
if (code==CI) 

1 4 outputHTML++ = c:Ipos++;t 
else switch(code) I 
case kTab: 

5endTab(outputHTML.Ipos): 
break: 

case kftewlineCommontPlus: 

-if t»(inputText!) !*■ *U»)-- 

I 

Closes pan(out putHTML); 
table * startlndex: 

) 


goto send_newline; 
case kPPnewline: 

if (quoteCounter & 1) //unmatched quote 

Op enS p an(out pu t HTML,kHTML string): 
table " stringlndex: 
goto send_newline; 

) 

//else table = startlndex; 

//goto sendeewline; 

case kNewlineText: 

table = startlndex; 

send_newline: 

ease kNewline; 
case kHewlineStart; 

SendNewiine(c.inputTexi,outputHTML) : 

lpos=0: 

break; 

case kCoimnentReturn:// from a C-Stylc common 
*OutputHTML++ c;lpos++; 
if (inputText[1] = */ p ) 

I 

‘outputHTML++ ” * i ++lnputText; 
table = returnTable; 

CloseS pa n(q u t put HTML): 

) 

break; 

case kStart2Text:// first nor+whitesparc, not * 
table^ext Index: 
goto evaluate; 

case kSta rt Prep roc essor: // valid #, probably Preprocessor 
len = Preprocessor(inputText.PPstate): 
if (len) 

f 

SendKeywords 

(c,inputText,len t out putHTML.1pos); 

if {PPstate = kPPsimple) 

ft just regular text from here 

table “ textlndex: 
else 

{ ft PP deals with the whole line 

quoteCounter » 0: 
table - preproclndex; 

) 

break: 

I 

// not a PP keyword after all 
table “ textlndex: 
goto print_one; 

case kPPstring: // a string argument in preproc 

ft does not get string colored 

if (quoteCounter & 1) 

{ 

if (" (inputText -1) !“ *YW 
quoteCounter ■ 0: 

1 else quoteCounter - 1; 
goto print„one; 

case kBasicKeyword: 

len^GetKeywords(inputText.plain); 
if (len) 

f 

SendKeywords 

[c,inputText,len.outputHTML,ipos); 
if (plain) 
c - *++inputText; 
else break; 

1 

if (plain) 

-f--- 

SendPlain 

( c *inputText,plain.outputHTML,lpos); 
break; 

I 
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goto print_oiie: 

case kGotoComment: // either type might s»tan 
if (inputText[1] — 1 *') 

f 

OpenS pan(outputHTML.kHTMLcomment); 
returnable “ table: 
table = commentIndex: 

I 

else if (inputText[ll ** */') 

I 

QpenSpan (outpu t HTML. kHTMLeoimnent J: 
table “ commentPlusIndex: 

[ 

// not a comment, but wc still must send char 

goto print_one; 


I 

table * textIndex; 

CloseSpan(outputHTML); 

1 

break: 

case kEndo ftext j // the terminating 0 was found 
return outputHTML: 

default: // character needs cootxling for 1II ML 

if (table “ startlndex) 
table = textIndex; 

outputHTML s 

SendCode{code.outputHTML); 
lpos++; 


case kText2String: // normal start of a string 

if ((lpos={)} || 11sLiteralfinputText)) 
I 

OpenSpan (outputHTML,kHTMLstring); 
table = stringlndex; 

J 

goto prlnt_one: 

case kEscapeString: // handles Vsequence in string 
if (inputText [l] — ,M, J 

f 

*outputHTWL++ " c; 

*<mtputHTML++ - ‘++inputText ;lpos-H*2 ■ 
break; 

J 

prim_one; 

'OUtputHTML++ - c;lpos++: 
break; 

case kString2Text: // return from string to normal text 
*outputHTMLH - c;lpos++; 
if [*(InputText-1) !“ *\\’) 


)// end of switch 
J 

return outputHTML; 

I 

I textConverier: 


//The entry from the test program; 


QoHTMi. 


long /* output length 7 CtoHTML? 

const char * inputText. /* text to convert *f 

cha r * out pu tHTML. t converted text *$ 

const Settings displaySettings t display parameters V 

} I 

char* start * outputHTML; 

a utputHTML = OpenPa ge(output HTML.dis playSet tlogs): 


Ma keTa b s Ar ray (d i s p lay Se 11 i n gg;-t*b-£>tz e) 


outputHTML = 

textConverter.ConvertText(inputText , outputHTML); 



Impact Your Market 



Internet Wire, Inc. 

4676 Admiralty Way, Suite 521 
Marina Del Rey, CA 90292-6695 
1 -800-I WIRE 
infu@internetwire,com 

Be sure to visit our website at wwwJnternetwire.com 


Unmatched Distribution 
From press releases and media alerts to 
corporate earnings and Web site announce¬ 
ments, internet Wire is the place reporters, 
analysts and consumers turn to for direct 
company news on the internet. 

Enhanced Exposure 

internet Wire’s targeted distribution has 
resulted in client coverage in leading print, 
broadcast and online media around the world. 

Added Branding 

internet Wire delivers added branding via 
dedicated vertical consumer channels, 
international distribution and long-term, online 
archiving ofyour company news. 


Call 1-800-77-iWiRE and find out why so many 
leading companies and PR firms depend on 
internet Wire to deliver their message to the 
world. 













outputHTML ~ CloseFageCoutputKTML); 

'outplitUTttL^O: 

return outputHTKL-start; 


Keyword.cp 


lilt trf sirinRs which appear colored as "keywords’ in the QxIcWarrior IDE J. J. 
Compiled by Krnsi Mumcr, 22 June 1999, 

This list may be incomplete 


7 

#tnclude “keywords*h“ 

const char* _Keyword[] * {“U\ll M * 

"_declspuir" I: 

const char 1 ^KeywordU - \ “\4\2\5 V3V3“ , 

“ nd " P "nd_eq“ . *sm“, "uto" I; 
const char* bKeyword|] ” 1“\4\5\4V3\4", 

“itand",“itor"*"ool H ,“reak"); 
const char* cKeyvordE] * l*\lQ\j\4\3\4\4U\lU7*\ 

w af:e" . "atch", “har“*"lass" - "ompl" , “oust"* “onst_cast“ * “ontinue' 1 

h 

const char* dKeyvcrdU « I"\5\6\5\lY5\13\ 

M efauit"*"elate*,"o".“ouble“*“ynamlc_cast*|; 
const char* eKeyvordH w r\5\3\3\/\5\5". 

“ise", “num“. **xpl iei t" * “xport" ,"xtern" I; 
const char' fKeywordp = l*\5\4\2U\2\5\ 

M alse“,"ar H , "loat* r “or*,“riend" 1: 
const char 1 gKeywordjl & l“\l\3" T 

const char' bKeywordf[ - l M \G"I; 
const char' IKeyvord f] 3 PY3\l\&\2*. 

*f H P H nline".“nt"); 
const char' JKcywurd[J = l"VtTI: 
const char* kKuywurd|j = 
const char* IKeyvord[| - |“Al\3“* 

“ong“ I; 

const char* raKeywordO “ l“ViV6 H P 
*utabie*h 

const char* nKeyword[] “ I **\4\ 10\Z\2\5", 

“ainespace" * *ew“ P “at *, "ot_eq“ I; 
const char* oKeyvord[1 = l“\3\7Vl\4“. 

“perator".”r"."i_eq“|; 
eonst char* pKeyvordf) - I“\4\5\fi\lO\5". 

“usual”,"rivate"protected',"ublic"]; 
const char* qKeywordf] = r\£T|; 
const char* rKayword[j “ l”\3\ Al/\5" P 
“egister”,"Mnterpm^cast"Return*I: 
const char* sKeywordfl » f“\7V4\5\5\5.\l2\5\5 M , 

“hort”, " [ gned" P "izeof “„ “tatic*, “tatic_cast**, *tmet" , "witch" I; 
const char* tKeyword[J - I"\10\7\3\4\3\2\6\5\/" P 

"emplate" t “his” . "brow" , "rue Vry'\ “ypedef ", "ypeid* . "ypeitame"} 

const char’ uKeyword [] * f n \3\4V7\4 w * 

“alon'V* Aligned", “sing" f; 
const char* v Key word [] = r\3\6\3\7 , \ 

"irtttal”* "old" . "olatile”); 
const char* wKeywordl] = [“\2\fi\4", 

~char_t” P "hiie"1; 

const char* xKeyward[) - l"\2\2\b", 

“or"*“or eq“J; 

const char* /KeywordH = l"\{Th 
const char* zKeywordfj = r\0” I; 

const char” basicTabief] - | 

.Keywords, 

^Keyword P bKeyword. oKeyword* dKcyword * eKeyword, 

IKeyvord. gKeyvord .hKeyword. IKeyvord, ^Keyword. 
kKeyvord * IKeyword P mKeyword, nKeyvord ^Keyword, 

uKeyword,vKeyword * wKeywo rd,xKeyword,yKeywo rd t 
zKeyword 
Is 


const char* aPPword[] 
const char* bPPword[3 
const chat* cPPwordtl 
const char* dPPword[] 
const char* ePPwordfj 
“lit",“lse“,“ndif". 
const char* fPPwordO 
const char* gPPwordf] 
const char* hPPword[] 
const char* iPPwordfj 
"f“,"fdef"."fndef". 
const char* jPPvord[] 
const char* kPPword[| 
const char* lPFvotri[j 
const char* rnFFwordf] 
const char* nPPword[] 
const char* oFPword[j 
const char* pPPword[j 
const char* qPPwordLl 
const char* rPPvordfj 
const char* sFFvordjl 
const char* tPPwordf] 
c oust cha r * uP Pwo rd t j 
const cha r * vPPvo rd[] 
const char* wPPwordj] 
const char 1 xFFwordl] 
const char' yPFword[] 
const char* rPPword[] 


= r\o"h 

- l“\0“l; 

“ l“\0"ii 

- rU\5 M ,“efine“|; 

- PU\3\3\4\4“. 
Vrror" 1; 

” r\0 "1; 

- (“\0"l; 

= f\ C"h 

= r\4U\4\5V6\ 
■nciuda"); 

- t"\0 M | 

= r\cr] 

“ P\l\3 w Piue“i; 

- (“VO'l 
= (“\0“| 

= [“\0"] 

- [ “\l\5 rt Pragma" I: 

- [“Vo"- 
“ f M \D"I: 

- r\0"l; 

- r\G"h 

= I M \lV4“Pndef“l: 

- P\0"h 

- I“\1\6“ P "arning"J ; 

- r\0“l; 

» r\o“i 

- r\o“i 


const char** preprocessorTablet] = l 
aPPword.bPPword,cPPword.dPFvord.ePPword, 
fP Pword,gPPword,hPPword.IPFword,j PPword, 
kPPvord *iPPword,mPPword.nPPword.oPPvord, 
(j PPword t qPPword, r PPword P sPFword. t PPword, 
uPPword t vPPword,wPPword.x?Pword,y PPword, 
z PPword 

h 


char* praginuUirective LkNumPragmal " I 

// list of 110 pragmas wliida llic CW IDE 3,3 display's in keyword color 

"abframes" p 

" a 1 i gn_a r ray _tEem.be r s , 

"always_inline". 

"ANSI strict"* 

*arg_dep_]ookup*. 

, *ARH_^:on^c^^ID , '. 

M auto_inline“, 

“bool". 

“check_header_flags". 

"code_seg" T 
"code6B020“, 

"coda6B8Bl", 

"cplusplus"* 

“cpp_extensions" P 
"dO_poititers n , 

"data_seg" P 
"def_inherited". 

Hh direct_destruction", 

"direct_to.som" P 
"disable_registers"* 

“d ollar_identifiers" P 
"dont_inline" p 
"dont_reuee_atrings w . 

,, ecpIuspI^ls ,, P 
"enumsalwaysint". 

"exceptions", 

"export", 

* e k t end ed_e r ro r c heck" P 
“far„eode" P 
"far_data”* 

"£ar_strings", 

“far_vtables", 

‘ farce r_pch_gen", 

“force active", 

“fourbyteints". 

"fp_contract“. 

"fp_pilot„traps“* 

"lunction", 

•“global_optiM^er"t— 

“tEEEdoubles". 

“ignore oldstyle" P 
“import"* 
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Keywords 


"inlt_seg* t 
“tnl i nejTeptir, 
“internal* * 

*k6Jd\ 

"k63d_calls*\ 

“lib export". 

"longlang** 

"longl ong^emjms", 
“macabug" f 
"mark". 

"mmx", 

“jnpvc". 

"ntpvc newline", 

”mpwc, relax*, 
M near_code*, 

"na^rcgiater_cnlor \ ng“ p 
■‘oldstyle^HyiDbols", 
"once", 

*only_etcLkeyvords"* 
“optimization.level". 
"optimize for size”, 
"optimization level", 
“options", 

“pack”, 

"parameter*, 

“pcrelstrings". 
"peephole". 

"pointers in A0 M . 
“pointers in DO", 
“pool^st rings"* 

*pop“ P 

"precompile_target”. 
“profile", 

“push*. 

"readonly, strings". 
"require prototypes"* 
"RTTI". 

"schedul log"* 

"segment. " t 
"side^effects”, 

*smart_code*. 
"SOMCallOptimitation". 
“SOMCallStyle”, 
"SOMCdisckEiwironment". 
“SDHClaaaVe rs3 on", 
"SOMMetaClass", 
“SGHKeleaseOrder". 
“stack_cleamip'\ 
"atatiOnlines". 

*sym*. 

"syspath once", 
"tocjdats". 

"Ltacoback”, 
"trigraphs*. 
M unsigned_char”, 
"unused". 
“wam_emptydecJ". 

"warn ..extra comma", 

“warn hidevirtual"* 
*warn_l11 pragma". 
”warn_ltitpllci tconv". 
“vexnjnotinlined", 
"warn.possunwanx", 
"warn_unusedarg". 
"warn_unusedvar", 
“warning"* 
“warning_errors". 

"wcharetype" 

U 


const char* pragmaVaiuelkNumPragmaValue] - I 
//When uistd in a colorized pia^ma, these words are also colored 

"list", 

"on". 

*ofr*, 

“reset* 

n 


^include <cstring> 
f/include "c2htmlCommorv,h" 

extern unsigned char cmap[]: 
extern const char 1 * basicTablef]; 
extern consl char 1 p ragma Valuef]; 
extern char* pragmaniroct i vefj : 
extern const char 11 preprocoaaorTablc■[] : 


struct Keywords 

struct Keywords I 

// Collection of functions for looking up keywords in tables 

bool IsBasicKeyword[const char 1 w.itit len) 

I 

const char c = *vH-; 

-len: 

if (craapf(int)(unsigned char)(c)J 6 lowldent) 

I 

const char 1 * table ra basicTable[c‘1; 

const char* dESC*"“table; 

int nuEnWords = *dc£c: 

for [int i=l ;i<=nuniWorda;i - H‘) 

I 

int kwLen=*++desc; 
const char* kw^* Stable; 
if [kwLen != len) 
continue; 

if [0 — stdi;st rncrop(w,kw*1en)) 
return true; 

I 

I 

return false; 


int IsFreproeessorKcywordfconnt char* w T int len) 

// returns: 


Macintosh Fite Sharing 
Using Internet Protocols 


ShareWay IP 


ShoreWuy ‘ IP, from Open Door Networks, enables any Mat's built in Personal File 
Sharing to work using TCP/IP ins lend of AppleTalk, With ShareWay IP installed, 
you can easily share files aver ihe Internet or an infraneL 

Since ShareWay IP uses File Sharing, accessing fries is as simple as using the AppleShare 
dienl in the Chooser, ShareWay IP even supports Apple's new Network Semites 
Location, enabling dynamic browsing and poinl and click access. 

ShareWay IP also works with any AppleShare compatible server, so all your 
ser v ers ca n provi de Maci ntosh fi le shar i ng usi n g TCP/I P. ^ 


Open Door Networks, Inc, 
800/480-DOOR 
sales@opefidoorxom 


Open Door 
Networks 


http://www.opendoor.com/swip/ 
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// kPPspoiled if nor a keyword 

// kPPsjmple if simple 

// kPPindudc if include 

// kPPpragma if pragma 

I 

const char c ■ *w++; 

-len; 

if (cmapf(int)(unsigned char He)] & low) 

{ 

const char" table^ptepracessorTable[c*'a*J : 

const char* desc & *table: 

int numWords =, desc; 

for (int 1*1 :i<“mimWords;i+-^) 

t 

int kwLen"*'L+deKc : 
const char 1 kw=*++table; 

if EfkwLen “ len) 64 (0 = std: ;strncinp(w h kw t ien))) 

if {[ c == 1 i *) 66 (i“4)} 
return kPPinciude: 
if (c“*p‘) 

return kPPpragma; 
return kFPsimple; 

1 

I 

1 

return kPPspoiled: 


bool XsPragmaDirective(const char 4 w*int len) 

I 

const char c “ *w++: 

-len: 

const char" pdh * pragmaDireetive; 
for t int i“0; KkNumPragraa: i++. pdh++) 

const char* pdp ^ *pdh: 

if ( (c *pHp) 64 (0 — std::strnemp(w h 1+pdp, len)) ) 
return true: 

) 

return false: 

1 

bool IsPragmaValue(const char* w.int len) 

l 

const char c - *w++: 

-len; 

const char** pvh - pragmaValue; 

for (int i“0;i<kNumPragDiaValue:i++ < pvh++) 

const char* pvp ■* *pvh: 

if C (c “ *pvp) 66 (0 “ std: rstmcrnp (w> 1+pvp*len)) ) 
return true: 

I 

return false: 


I: 


myCType.cp 

(/include "c2htmlCo&mon.h" 
unsigned cher cmapl256) * [ 

0* 0, 0. O t 0, Oh Oh Q f vsp t nln h 0*nln* 0* 0, 0. 

0, 0. 0, 0, Oh 0. 0, Oh 0* 0. 0, Oh 0. Oh 0, 0, 

wsp.pun h oth,pun * pun.pun.orb * oth.pun * pun*pun,pun,pun*pun.pun *oth * 
dig,dig,dig,dig,dig t dig.dig,dig,dig,dig.pun.pun*oth*pun h oth,pun* 
pun * upp,upp,upp * upp * upp,upp £upp, upp ,upp,upp.upp,upp,upp,upp.upp, 
upp * upp *upp ,upp *upp* upp.upp.upp.upp,upp * upp h pun,pun,pun,pun.und. 
pun,low,low*low,low.low,low,low.low.low,low h low h low,low,low.low. 
low,1ow,low,low,low * low.low,low*low.low.low,pun.pun,pun * pun * pun * 


0* 0. 

0, 0* 

0* 

0. 

0. 

Oh 

0* 

0* 

0* 0* 

0* 

0* 

0* 0. 

0* 0, 

0, 0* 

0* 

0. 

0* 

0* 

0. 

0. 

0, 0* 

0. 

0. 

0* 0, 

0, 0. 

0, 0* 

0. 

0. 

0* 

0* 

0* 

0. 

Oh 0* 

0, 

0, 

0* 0. 

0, Oh 

0* 0* 

0, 

0, 

0 , 

0* 

0. 

0, 

0* 0* 

0, 

0* 

0. 0. 

0, 0, 

o,_o, 

Q t 









q. 0 - 

o, o! 

0* 0, 

0, 

or 

0* 

0* 

0. 

o[ 

o* o! 

o! 

o! 

o, o! 

0. Oh 

0* 0, 

0. 

0, 

o* 

0* 

0. 

0, 

0, 0, 

Oh 

o* 

Oh 0, 

0, 0* 

0* 0. 

0. 

0* 

0, 

0. 

0, 

0, 

0, 0. 

0, 

0 , 

0. Q 


HTWILstrings.cp 


// Canned HTML header and trailer 

const char * kHeadl = *\ 

< tOOCTYPE HTKL PUBLIC \"-//W3C//DTD HTML 4.0//EN\"\n\ 
V"http;//www.w3.org/TR/REC■html40/loose.dtd\">\n\ 
<htmlKhead>\ 

<STYLE TYFE=\"text/css\">\n\ 

<l-\npre I color:xOOOQO0; font:": 

const char* kHead2 = )\n\ 

</STYLE)\ 

</head>\ 

<body bgCQlor=\"#FFFFFF\")\n\ 

<pre)V'; 

const char 4 kTail = *\n</pre></body)< /html >\n"; 

//The HTML encodings & < > and for extended Apple characters. 

// Apple characters without HTML equivalents become ? 

const char* encoding = 

*000^ 

038:060:062:\ 

196;197;199:201;209;214:220:225:\ 

224;226;228;227:229;231:233;232 
234;235;23 7;236:238:239:241:243;\ 

242;244;246;245;250;249:251:252 
134;176;162:163:167;149;182:223;\ 

174;169;153:180;168:063:198;216 
063:177:063;063;165;181:063:Q63;\ 

063:063;063:170;186:063:230:248 
191;161;172;0fi3;131:063:063;171 
187:133;032 :192;194:213:140 :156:\ 

150;151;147;148;145:146:063:063:\ 

255;15 9;04 7;063:139:15 5;06 3;06 3:\ 

135;183t130;132;137:194:202:193:\ 

203;200;205 :206;207:204;211;212;V 
063:210;216;219 :217:063;136;152;V 
063 ; 063; 063 ; 063 ; 063; 063 ; 06 3 :063 :": 


HTMLstrings.h 

(/include ^cZhtmlCommon.h" 

extern const char* kHeadl; 
extern const char* kHeadi; 

extern const char* kOpenSpan[4]: 
extern const char* kCIoseSpan; 
extern const int kCloseSpanLength; 
extern const int kOpenSpanLength; 

extern const char* kTail: 
extern const char* encoding: 

inline char* SendCode(int code*char* output) 

const char* cp * encoding + code l 4: 
output [0] = H V: 
output11] = " # 4 : 

#if macintosh 

4 ((long*)(output+2)) * *((long 4 )(cp)); 
#else 

output[2] = cp[0l; 
output[3] - cpfJj; 
output[4] = ep[2); 
output[5] = cp[3]; 
feidlf 

return output*6: 

) 


Struct HTMLcodcs 

struct HTMLcodes l 

unslgned cha r c ornmonlnd ex[25 6]; 
unsigned char startlndex(256j: 
unsigned char text Index [256T: _ 
unsigned char stringindexi256]: 
unsigned char coiMientIndax[256] ; 
unsigned char commentFlu&Tndex[256] : 
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No Cute 
See-Through 
Green Panels 


Unlike some high-tech companies, Zocalo 
isn't reaching out to the mass market. 
We've been serving business, industry, 
and higher education exclusively for 
more than a decade. So your business' 
Internet traffic doesn't queue up behind 
some kid's game of Doom, and your 
network staff don't have to waif on hold 
to speak to our technicians. 

By focusing on the high-speed networking 
needs of businesses, we've been able to 
build an Internet backbone that provides 
better than 99.995% overall uptime. 

With peering at more West Coast 
locations than any other ISP, we're 
uniquely able to route your company's 
critical data around Internet slow-downs 
and trouble-spots. Our managed 
multiprotocol network is the only one of 
its kind, allowing Zocalo alone among 


ISPs to offer native routing of AppleTalk, 
IPX and DEC net between customers' 
office LANs throughout the world, at 
speeds up to 45 megabits per second. 
We also deliver fully-configured 
equipment, proactive customer service, 
on-site maintenance, and a firewall 
custom-built to your specs, all at no extra 
charge. We take responsibility for your 
wide-area network and Internet 
connection right up to the FDDI or 
Ethernet jack in each of your offices. 

If cute just isn't enough for your business, 
call our network engineers and find out . 
why Zocalo is the first choice for £ I 
industrial-strength business networking. 

+1 510 540 8000 

infp@zocalo.net 

http ://www .zocalo. net 


Multipoint Internet Access 





unsigned char preprocIndex[256]: 

HTHLcodest) 

I 

// constructor sets up the code tables at pmgram start 
MakpCommnnTrtdcx C) ; 

MakcSlarllndex(s t a r Undex); 

HakeTextindex(textIndex ); 
MakeStringlndex(stringlndex )i 
MakeCotiMentindex(cosmienTlndex) ; 

Ha keC onmentPX USInd ex(commeutPlusInd ex ); 

Hake P r e p rocIn dex E preprocInd ex); 

I 

void MakeCommonIndex{) 

I 

std; :memset (commonlndex.G.siseof (coimncmlndex)); 

common!ndex [OJ ^kEndoftext; 

commonIndex[0x09]“kTab: 

commonIndex[0x0A]=kNewline: 

commonIndex[Ox0D]“kHevline; 

common T ndex [Ox IA] "kEndof t ext: // DOS files’ 

commonIndex['6*1 *kAmp ; 

commonIndex['< *]=kLt; 

commonIndex[*>* j=kGT; 

for (int i"3 28:K256:i++) 

[ 

comtnonlndexfi] “ Ei-I28) + kExtended: 

I 

I 

void HakeStartindex(unsigned char* x) 

I 

std; :memcpy(x,coii!monltidex t siEeof (commonIndex}); 
x[OxQA]*kNewIineStart; 
x[OxODl=kNewlineStart * 
x[*#'] *kStartPreprocessor; 
for {int c H< 1 +i;c<I28;H+) 
if Cx[c]=G) 

x[c]=k£tart2Text: 

1 

void MakeTextIndex(unsigned char* x) 

I 

5td ; tmemcpy (x*cnrtimnnTndex.sizeaf (conmonTndex)); 
x[OxOA] ® kNowlineTexi: 
xtOxOU] - kNewIineText; 
lor (Int ;cC=*x * ;c++) 

x [c ] *■ kBaslcKeyvo rd : 
x[ , “ , l - kText25triftg; 
xf'/'l - kGotoCoannent; 

1 

void HakeStringlndex(unsigned char* x) 

I 

std:; tnemepy(x.commonindex* sizeof £ commonIndex)); 
xi*U*J “ kEscapeString: 

^ *[■-*] - kString2Text; 

void MakeComme nr. I ndex (unsigned char* x) 

I 

std:: metnepy (x tcomanon I ndex, sizeof (common I ndex)); 
x[* * * ] * kCummenLketurn; 

1 

void Make Comment PlusIndex(unsigned char 1 x) 

t 

std;:memcpyfx,commonIndex,sizeof{commonIndex)}; 
xfOxOA] “ kHewHnenommenrPlus; 

xfOxOn] ** kNewl ineComnentPlus: 

I 

void MakeFreprocIndex(unsigned char* x) 

std: -memcpY (x« common Index* sizeof(common Ind ex}); 
x[GxGAj - kFPnewline; 

xlOxOD] - kFPnewline: 

xf * *’ * 1 - kPPstring; 
xf'/*) - kGotoComment: 

1 

It 


c2htmlCgmmon,h 


tfifndef C2HTMLCOKHON 

ifdefine C2HTMLCOHMON 

euutn ( 

kFPspoiied, 
kFFsimple* 
kPPpragflfl. 
kPPinclude 
Jt 

onuBi { 

kHumBasic “ /6* 

kfJtnnPreprocessor= 13* 
kNumPragma — 110. 
kNumPragma Value ** 4 

li 

enutn ( 
low = I, 
upp = 2. 

und 4* 
dig - 8. 
vsp = 16. 
nln - 32. 
pun = 64, 
olh = 128. 

lovldent - (low | und)* 
ident " (low | upp | undK 

word = (ident | dig)* 
txt = (word | wsp [ pirn)* 
nokey = (upp [ dig | wsp | pun) 


enum f 
kAmp * 1, 
kLT - 2, 

kGT = 3 t 

kExtended = 4* 
kTab = kEx tended + 128, 
kHewiine* 

// codes in Sun state 
kHewlineStart, 
kStart2Text. 
kStartPreprocessor, 

// codes in Text state 
kNewiineText * 
kBasicKeyword* 
kText2String, 

kGotoCorament. // also from the preprtMXSSor states 

// codes in String state 

kEscapeString, 
kStrlngZText. 

// codes in Comment state 
kCommentRetum, 
kNew line Coalmen t P1 u s, 

// codes in Preprocessor state 
kPPstring* 
kFPnewline * 

kEndoftext 

)T 

#endif 

m 
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WEBTECH™ 


By Ron Davis, Pervasive Software 
Contributing Editor, John Daub 


Learning to Tango 


Dynamic web sites 
in no time 


Note that with the exception of the description of the Project 
tab of tlic workspace window, all of the code in this article is 
based on Tango 3.6. 


These days everybody has a web site. 
They start out as a single ugly page of text 
and gradually grow into a monster web of 
hyperlinks. Somewhere along the line of this 
evolution the person creating the site starts to 
think, “'lliere’s got to lx* a IxHter way." Well, 
it turns out there is a better way; Tango, 
Tango is a web application builder 
and server. It consist* of two parts; The 
Developer Studio where you create your 
Tango Application Files (TAF) and the 
Tango Server you hook up to your web 
server to actually serve the TAKs. TAPs art- 
files that contain instructions for doing a 
series of Actions. Actions are Lliings you 
want to happen Lo create a web page, 
such as accessing databases, logic based 
cm arguments, variable or cookies, or 
sending an e-mail message, 

TAFs are uploaded to your web site. 
When a user requests a L IRL that refers to a 
Ole ending with the aaf extension, the 1AF 
file is “executed". Tltis means the Tango 
plug-in or CGI interprets the TAF, going 
through its logic and doing the actions 
stored in it, and then outputting HTML that 
is passed buck to the user's web browser 
hi this article you are going lo actually 
create some TAF files and execute them via a 
web browser and server. If you want lo do 
lire examples, you will need to make sure 
Tango is ser up correctly. Read the 
documentation for details on how to do this. 


The Tango Server 

Let’s talk a minute alx>ut how the Tango Server works. 
Pervasive doesn't make an HTTP server; instead die software 
integrates with a number of other web servers. This is done in 
one of two ways on the Mac, either through a WehStar plug-in 
or through the Tango CGI. The Webstar plug-in supports 
StarNine's WehStar plug-in API, so it wall work with other Mac 
web servers that support this API, like Quid Pro Quo. The CGI 
works with a number of other web servers, including personal 
web sharing which is built into Mac OS 8.x. TAF files created on 
the Mac can also be deployed to web servers on Windows and 
Solaris. In Tango 2000 these TAF files are XML, 

The main difference Ixtween these* two methods is what a UHL 
that refers to a TAF kxiks like. Using the 1 plug-in, rhe web server 
knows how to handle aaf files, so the URL looks pretty normal, 

http://wvm mactech.com/home, taf 

If you are using the CGI you have to explicitly say that in 
die URL, SO if looks like this: 

http://www.niactech.com/itango.acgi7home.taf 

For the resL of this article it will lx* assumed you are using 
the plug-in and the “Stango.aegi? 7 ’ part of the LULL will be left out. 

No matter which mellwxl you use to access a TAF file, die 
server handles doing all of the things you've coded into the file 
using die Developer Studio, The Tango Server is very robust. 
Tango is used to nm the Jokes.com (http://www.jokes.com/) web 
site. Ibis web site gets 8 million hits per month and sends out 
10,000+ e-mail messages a day. Tango also serves news for The 
GloIx.com <http://www,theglobexom/>, a national ISP. 


Ron Davis <rdavis@pervasive com> is a Senior Software Engineer at Pervasive Software in Austin, Texas. He works on the 
Macintosh version of the Developer Studio. In his spare time lie creates a Tango-based web site for reviewing science fiction. 
The fad thus site isn’t public yet reflects how much free time he has. 
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The Developer Studio 

'rhe Developer Studio is where you develop your web 
application. Here is a quick tour of the Tango Editor. When you 
open the Tango Editor application you will be presented with 
the Workspace window, Figure 1 The Workspace contains tcx^ls 
and information that are application wide and that you will use 
throughout your development of TAF files. In Tango 3,6 there 
are three tabs: Project, Data Sources, and Snippets. Tango 2000 
adds a fourth tab: Objects, 


□ =. — Workspace =^- —^ 

f Projeel \f Gain Squreqq\/Sni ppets\/0 b jetta 



A 

v 

<1*1 H> r 

m 



Figure 1. I he Workspace Window 


The Project Tal> 

Tango, just like Code 1 Warrior and a variety of other 
development environments, supports Projects. A Project is a 
collection of elements that are used in one design. In Tango 
2000 these include: 

* Files, which are the TAP files in the project. 

* Presentations Pages, which are the equivalent of a C 
^include file, 

* Data Sources, which ate databases that are used in the project 

* Objects, which are other executable axle modules that ate 
called from the TAP. 

* Sites, which are FIT directories where you deploy your web site. 

You can only directly change the Files folder and the Sites 
folder The contents of the other folders are determined by what 
you reference in the various Actions used in your TAF files. 

The Data Sources Tab 

In Tango, all databases aie called Data Sources. You can 
connect to a dam source via a number of different methods, each 
of which has a folder in the Data Sources tab. They are D AM, the 
Data Access Manager. ODBC for connecting to SOL databases, anti 
FileMaker lor accessing FileMaker Pro databases via AppleEvents. 


Before a database can be accessed from a TAP, you must 
create a Data Source for it. 

The Snippets Tab 

Tango supports the idea of snippets, which are little pieces 
of text you can add to lots of places in Tango via drag and drop 
or by double-clicking. Most of the snippets in the folders in rhe 
Snippets tab are read only, but you can add vour own to the “My 
Snippets” folder. 

The Objects Tab 

New to Tango2GG0 is the ability to call axle modules from 
inside a TAF. In the case of the Macintosh these code modules 
are either Java Beans or Tango Class Piles (TCP). TCFs arc like 
TAFs, but have an object interface to them. 

Obviously, this is a very shallow overview of the workspace 
window. You can read the documentation that comes with 
Tango for more details, and youll learn by doing the examples 
in this article. 

Tango Application Files 

Tango Application Files are the heart of Tango. It is here 
you create the dynamic nature of your web site. You are going 
to learn about these files by doing. If you are in the Tango editor 
create a new* TAF file from the File menu. Youll get an empty 
TAF window that looks like Figure 2. 


□ . Untitled Ltaf : E 

B 

Action | Attributes 1 D«ta Source f Comment 


g) Uni it Ml 

•>r 

<in T UL 


Figure 2. A new TAF window 

In Tango you create code by dragging a series of Actions 
into the TAF window. If it isn't already open, go to the Views 
menu and select the Actions Palette, 

□ Act inns S| 

|f\ $ & 9 W ¥ 3. El ^ 3 B ? = [■ [i IS |£ BB «•■•*■« >>| 


Figure £ The Actions palette. 


Each of the icons on this palette represents a different type 
of action. If you run your pointer over the icons the name of th e 
action will be displayed under the icons. To add an action you 
drag it off the palette and into the T AP where you want it. Let's 
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create a simple TAF to show just how easy it is to create an 
interactive web site with Tango, 

First drag an If action into the TAF window. When you do, 
the action will open a window like this. 



There is a lot of flexibility in this action, but we re going to 
keep it simple. The cursor is currently in the first Value column, 
so go ahead anil type in H <@ARG functions. Then tab twice to 
leave lhe - sign the same and get to the other value column. 
Type in “Mom”, Now close the window. 

What have you just done? You created an if statement that 
is going to check for a passed in Argument named Junction and 
evaluate to True if it equals Mom. Tango lias its own set of HTML 
like tags that can be inserted into various parts of Tango, 
including if statements and normal HTML All of these tags start 
with “<@" and end wall The word ‘ARC 1 ’ denotes an 
argument to this TAF. There are a lot more of these tags referred 
to as MetaTags in Tango. 

So what is Tango going to do if the If statement is true? 
Right now nothing, but lets fix that. A Results Action allows you 
it insert strait HTML into the dynamic page you are creating. You 
can also include Tango MetaTags which are interpreted by the 
server prior to adding them to the output HTML Drag in a 
Results Action. When you drag it under the If it will be indented 
unless you work at getting it to go to the left. 

The Results Action window pops up for you to edit. Here 
we want to insert some HTML that will lie displayed to the user 
if <®ARG JunctJon> is equal to “Monv. Type in the HTML in 
Listing 1 and dose the window, 

Listing 1: Mom page HTML. 

<HTHL> 

<TITLE>H 0 tn’s Fage</TITLB> 

<BODY> 

Hi Mom! 

</B0DY> 

Now we need to handle the non-Mom case. Drag an Rise 
Action into the TAF, Ixdow the Result Action but at the same 
level as the If Action Then drag in another Result Action under 
the else. Type the HTML from Listing 2 into the Result window 
and close it. 


Version 
Control 
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Macintosh 
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Control Tool for 
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Listing 2: NonMoin page HTML. 

<TITLE>NonMDm f a ?age</T!TLK> 

(BODY) 

HI Non Moral 
(/BODY) 

(/HTML) 


You Ye now written your first Tango Application. Save it a* 
"parents.taU and put it where your web server is going to find it 
and point your browser to it with a URL like this 
<http://www.yourserver,com/parents,taf>. 

Your browser should display something like this: 


□ non Mom's Prtqe SB 

6atfc — t .k : Pc-frfth Kww FfYarite* History Seare+i 

Addrrsj | a /par tif | Goj C| 4 

Hi Him Morn 1 

w 

TIT; - ! HIT 


0 too*! ZW* 



Figure 5* N<mMom page in browser 


Now I want to show you how arguments ate passed. Change 
the URL to <http://vww.yourservero)m/parents.taf?JunaiDn=MorTi>. 


Executing that you will get a completely different page. 

"c Pari a 

R*fr*sh Monw Fivarttes History Search 

Addr«s: W&Lm***. i \&&>\ i 


til Mom! 

A. 

"W 

* M 1 TuT 


Q Local-machnw 



Figure (\ Mom page in browser. 


Now you can see how to pass arguments manually in the 
URL, but that doesn't look very useful. Let us see a couple of 
ways this could be used. First, you could include the URL with 
argument into a hyperlink. Add the following line to the Non- 
mo m result HTML. 

(A HREF= H (@CGI><§APPF ILE>7 _functisn^Hnw"■ >Visit Mom( / A) 


Save you file anti reload it in your browser. You'll now see 
a hyperlink on the page. Clicking on it will take you to the Mom 
page. Let’s look for a moment at what we added. You'll notice 
the place where you would put the URL contains the cryptic 
“<@CGI><@APPFILE>'\ From the <@ notation you probably 
figured out these are Tango MctaTags, but what do they mean? 
These two lags create a URL to the TAT file currently lie run. 

The <@CGI> will insert the notation needed to execute via 
the CGI interface we talked alxxil at the !x k girming of the article 
if you are running the CGI. It inserts n othin g if you are using the 
plugin. It is a good thing to always include <@CGI> even if you 
never intend to use the CGI, because you might need to one day 
and or you might want to give your TAF lo someone who does. 

The <@APPF!LE> tag inserts a path to the current file. You 
don’t have to figure out relative links and such, and you don't 
have to change a bunch of HTML if you move the file. 

Another way arguments get passed around is via forms. 
When a fonn is processed it creates arguments based on the 
values of the various controls and passes them to the action file 
when the Submit button is pressed. You’re not going to get to 
see an example of that right here because we've milked this 
simple example as far as ii will go. but we are moving to a new 
more complicated example, so watch for it. 

Tango and Databases 

Having logic and a means of passing Information from one 
page to another is enough to make Tango coo! for die web 
developer, but those abilities just scratching the surface. You can 
do all kinds of interesting things like sending e-mail, or 
executing an AppleScript But Lhe ability that really makes web 
sites dynamic and shows off the abilities of Tango is how 7 it 
works with databases. 

For this example you are going to create a simple user 
management system for a web site. Users will be able to sign up 
for the web site, selecting a username and password. This 
information will lx* entered into a database along with assigning 
a minimal user level. Then you'll create a TAF that allows you 
the administrator to change a user’s information or delete them. 

Creating a FileMaker Pro Data Source 

To start off we need to create a (lata I vase to hold the users. 
Tango supports a number of databases. For this article you can 
use FileMaker Pro. Launch file maker and create a new database 
with three fields, username of type text, password of type text, 
and userievd of type numlw. 

Once you have the database created you need to create a 
new Data Source in Tango to access the data base. With 
FileMaker still running, go to Tango and select he menu Data 
Source- >New->FileMaker. You will be presented with a dialog to 
select the FileMaker application. For this example just use the 
default, which is "Any FileMaker application” and click OK. You 
will next lx* asked to select a database. Assuming you named 
your database UserDB you r-d t alqg will look like Figur e 7. Select 
UserDB and click OK. 
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Figure 7 Select FileMaker Pro database dialog. 


Next you will )>e asked to name your dam source, just name 
it the default, which is the .same thing the database was named 



Figure & Select a Data Source name dialog. 

Now you have a new Data Source in the Data Source panel 
of the Workspace window. Expand the disclosure triangles and 
you will see the layout of the database, FileMaker creates a 
number of secret fields. One is die layout 0, which is an invisible 
layout. Also each layout has an invisible recordjd field. You will 
avoid working with either of these for this example. 

The New Record Builder 

Now we can Start working with the database. The first thing 
we need to do is create a way of adding a new user to the 
database. Tango offers two powerful tools for creating a bunch of 
axle to do die two mast common database tasks, adding a new 
record and searching a databa.se via a TAF. Hie New Record 
Builder helps you add new records to the database and the Search 
Builder helps you search for records and change or delete diem. 

Create a new TAF' called "newuser.iaf". In the actions palette, 
drag a New Reconi Builder into the new TAF'. You get a w indow 
that allows you to configure this builder To create a page to allow 
us u> add a new user we need to tell the builder which columns 
we want to create. To do this we drag those columns from the Data 
Source panel to die Columns area of the builder. Drag over 
username, password and usedevel from Liyoui^l. 

You can set various options for each column as well In 
your case you want die default liehavior for the username and 
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password fields, but you want a fixed value for the userlcvel 
field. So select just the userlevel column in the builder. On the 
right side of the builder you get options lor this column. Click 
the Fixed value radio button. You can popup the Value popup 
and see some of the things you could enter here. Right now 
leave the value popup on “Value Entered* and then type *1" into 
the text box. You are now done with the builder and it should 
look like Figure X. Click the Build anti Close button to save your 
changes to the TAR 



figure 9. New Record Builder. 


Suddenly there is a bunch of code in your TAF file. You might 
want to !cx>k at tlx? code lo see what it does, but for now jusi know 
it works. You can save the TAF file and run it tn your browser. You 
can enter a username and password into the form and hit Save. 
You’ll gel a message that the record was added. If you switch over 
to FileMaker, you will find that there is a new record in the 
database with the username and password you entered. 

The Search Builder. 

Using just the New* Record Builder you created the means 
to add new users to your web site in alxRtt 2 minutes. Now you 
need to administrate these users. You need to lx* able Lo delete 
users and change their information. With Tango this is almost as 
easy by using Tango's other builder the Search Builder. 

Create a new TAF called M adminusers.taF. In the editor drag 
a Search Builder from the actions palette into the TAF window. 
You'll lx? confronted with the Search Builder window. The 
Search Builder window is more complicated than the New 
Record Builder, but is still very useful and easy once you 
understand all of the things it can do. 

The Search Builder creates a series of pages for voir to 
select information from. First it creates a form to allow the user 
to enter criteria to search the database on. Then it creates a page 
•with the results of the -s earch at-a h i gh l e vel F,a<4> kem on this 
“Record fist” page is a hyperlink to more in-depth information 
ihat can lx* edited on the "Details Page", 


For your user database you will create a search by user 
name only. Then you can display a list of user names and user 
levels of the results, and the details page will allow you to edit 
all of the columns of the table. 

Take the username column in the Data Sources and drag it 
into the Columns panel of the Search tab in the Search Builder 
window. The right side of the builder window allows you to 
manipulate options for the search, such as whether to Find items 
that Ixgin with what's entered in the field, or contained 
anywhere in the siring. You can also choose something other 
than an edit field fur entry. You could even just have a fixed 
value for the search and skip the form field all together. By the 
way. if you skip entering anything in the search section it will 
find all of the records in your database. 



Click the Records List panel. FileMaker Pm does not support 
[inns so 1 1lose sub panels are grayed out in all of the Search 
Builder panels. Here we are going to define what we see when 
Tango displays the results of the search. You want to show the 
user name and the user level of each of the results. To do this 
simply drag those two columns from the Data Sources into the 
Display Columns section of the search builder. 

You 11 also want to list the results by user name .so drag the 
username column into the “Order By* panel on the bottom of 
the window. You'll notice you can set the number of records that 
are shown per page as well. Co ahead and leave the default 
values for this and the column display at the top. 
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If you didn't know then, you will now* Introducing MacBuy.com, The first and only comprehensive buyer's 
guide from the editors of Macworld magazine; with MacBuy.com you'll know.,- 


... which products to buy. And which to avoid. 

The best deals on the Web. And where to find them. 
How much it costs. And how much it's worth. 

www.macbuy.com 

The Macworld Buyer's Guide 



fcjssral 


As Easy as 1-2-3 
Whether you're searching for a 
product review or finding the Pick 
OF The Day. it's easy with 
MacBuy,corn's dean user interface 
and intuitive navigation. 


From the publisher of Moavodd magazine 

MacBuyf com 

Get it right 


Powerful and Easy-.,, 

to-use search engine. You can 
search by product or vendor name, 
or use the Power Search button to 
search by multiple criteria, such 
as rating and price. 

Support from Apple 

Literally, Built with Apple's 
WebQbjects. MacBuy.com is solid 
as...well a rock. 


Convenience and Value! 

The latest and lowest prices from 
leading Mac resellers. Plus, 
convenient links to their sites so 
you can purchase the product you 
want instantly! MacBuy.com tells 
you how to shop smart. 


Search Ftesu/fe 

















































Figure 1L Search Builder Record List f xweL 


Cl irking over to the Record Details panel you get to 
configure wltat Fields you will lx; able to edit in individual 
records. In tills example you are going to edit them all so drag 
username, password and user level over to the builder, 

This time you are going in be changing some of the Column 
Options for editing. Select all of your columns in the builder and 
click the Allow Update check box. You will now he able to edit 
alt of the fields. You also want to he able to delete users so 
check tite "Allow delete of record from:* check lx>x in the- 
Record Options section. Since you have only one table you don’t 
need to change the popup, 



and see what is Ixang done. 

Test your TAPs by using the newsusertaf hie to add a few users. 
Use these names- admin, bubha, bubbette, leruy, and alftecl 

Run the admi misers, taf file. Youll see a form with one field, 
Username, and two buttons Find and Reset Values, Click the Find 
button without entering any user name. Your results should look 
like Figure 13. This is a listing of all of the records in the database. 



Figure /JL Results of searching fur all records. 

Click on the admin link. You will now see the details page, 
which veil] allow you to change various columns. Change the 
admin's user level to 10, and click save, In the page that tells you 
the record was successfully changed click the link to search 
again. You might want to do another empty search again to see 
that the admin changed. 

At the search page, enter "bub* into the search. You’ll get 
back results for iiublxf and “bubbette”. It turns out these are 
the same person and you don't want multiple accounts per user, 
so we want to get rid of the bubbette account, The results of this 
search only show "bubha” and "bubbette*. Click bubbette and 
delete her from the Details page. 

The Log-in TAF 

There is just one more aspect of our member system we 
need to implement, the ability to log in. Create a new TAF we 
are going to name login.taP* What you need to do is create a 
form for the user to enter I heir username and password, then 
you will see if that user is in the database and if they have the 
right password. Then you want to in some way lxr able to tell if 
a user is logged in when they go to another page. In this case 
we will use a cookie. 

If you have looked at any of the code the builders built you 
will find the common TAF coding practice of using the function 
argument to control what part of a TAP is executed. You will use 
that in the login, taf file as well, So the first thing you need to add 
to the TAF is an If action. You want to make the condition lx; 
like Figure 14. 


Click the "build & Close* button to generate the TAF file. 
Again a bunch of code was generated, and it would l>e a gtxxj 
learning experience for you to look through the various actions 
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□ UiitmedS-tnft IfLogin ijlg --rS E 


Act hat \ \r * j 

If the follow ing ^yjujit^f to t^u*: 


Vain* j Op*r 

Vihrt 

JL. 

| I* Empty 



o r j _fuM4riw> [ “ 



yr 

i<N M» 



[ Advanced* :■ | 

—----r 


(TD) 

(INPUT TYPE""text” NAME-"userruune' , > 

(/TD) 

</TR> 

<TR> 

(TD> Password (7 TD> 

crr» 

(INPUT TYPE-"password" NAHE="password*"> 

(/TD> 

</TR> 

</TABLE) 

(INPUT TYPE-SUBNIT VALUE""Search") (INPUT TYFE=RESET 
VALUE""Reset Values") 

(/FORK) 

(/BODY) 

(/HTML) 


Figure 14 . If Action, 


Drag a Result adion below and inside the If action. Result 
actions are himl code that is put straight into the HTML returned 
to the Browser, In this case the HTML will define the log in form. 
Enter the following code. 


Listing 3= Login page Results HTML. 

<? DOCTOR HTML PUBLIC W/tLTT//DTD HTML 3,0//EN*> 

(HTML) 

(HEAD) 

(TITLE>Login< /TITLE) 

(/HEAD) 

(BODY) 

(FORM ACTTON-" (@CGI) <@APPF 1 LE>?_f u nc t i on=tfea r c h " METHOD-POST) 
(TABLE BORDER"”0“> 

<TR> 

(TD ) Use mane:</TD) 


Look at a couple of things in diis form, first the FORM ACTION 
is a POST method and die URL for the action is the current file. In 
that URL youVe set function to lx “search" which will allow us to 
branch correctly. Also realize that each of the input tags will lx 
passed as arguments with the mine given them in the <INPUT> tag. 

You need to add an Elself to login.taf. Then set the criteria 
to check that <@ARG Juncture* is equal to "searchThis will 
cause the Elselfs code to \k executed when the forms submit 
button is pressed. 

To test if tile user entered valid dam into die log in form we 
need to search die user database, so add a Search action to die Elself 
in login, taf You need lo select the usemame and password, so drag 
diem into the Selected Columns area. Now dick over to the criteria 
tab. You only warn to find the records of the database that am die 
same as the entered information. To do this, you drag columns into 
the criteria table and set what you want the criteria to be. In 
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Got Software? 
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Discover • American Express 





Phone: (310) 553-4054 


E-mail: brad@sniderman.com 











































this case you want to make sure the username argument and 
the password argument are the same as the username and 
password columns in the database. 

Drag in the username and password columns from the Data 
Sources. Edit the criteria so it looks like Figure 15 Notice you want 
to set the criteria Inch Empty Uj Ijc tme. If you don't do this, there 
will lx- no search on empty fields. Tltat means you could leave the 
password blank and always log in. 



After the Search comes hick you need to tiandle the two 
possibilities. First, the search may return no records because the user 
isn't in the database or their password was wrong. Second, die 
Search will return a record for the user. WliaL you will, do is check 
the results using actions in the TAP 

Drag an If action under tile Search action, making sure it is level 
with the Search and not the ELself. Anytime you do a search certain 
variables are created and set. One of those variables is 
<@NUMROWS>. which is the number of database table rows that 
were returned by the search, If <@NUMROWS> is greater than zero 
you found a valid username and password in the Searc h. In ournew r 
If action check to see if <@NUMRGWS> is greater than zero. 



login,taf: If 


If the foltowiog evaluitts to try*: 


1 

Value 

0p*r, | 

Vtlut 


j j ? | o 



T 

-illl 






scope to cookie. Set the name in the next column to 11 logged in’ 1 and 
set the value to "true*. Once tlus is set you ran ask for the variable 
named loggedin with the scope of cookie at the Lop of each page. 
If it is not there or not equal lo true the user isn't logged in Also 
realize variables time out in Tango if they are not used, so eventually 
the user will liave to k>g in again. 

Hie last tiling to do is ID handle the case where they logged in 
wrung. This is a simple Results action that tells them they screwed 
up and offers a link back to the log in page. Here’s the HTML for 
the result action, 

Listing 4 l Invalid Login Results!HTML, 

Invalid username or password. 

<P> 

<A HREJ*="<@CGI>PPFILE>? ftU^tion“logln*>Log in again.</A> 

That is the bastes of a user management system using 
Tango, If you did this in a traditional CGI language like Perl, 
AppleScript, or Pi IP it would take you a lot longer. In Tango it 
could lx done in an alicrntxm at the most. 

There are a lot of things this example leaves out T but it is an 
example and not a full system. It shows you some of the powerful 
things you can do with Tango in a short period of time and gives 
you a start toward a real user management system. If you want lo 
explore Tango more using tills example try adding the following 
features. Let the user Log-nut, this would involve setting the cookie 
variable to lx invalid. Also explore what would happen if the user 
tried to log-in twice. Make it so you can't log in twice. 

You’ve now taken the first steps in learning to Tango, and you 
need to get out on the dance floor and practice. I lopefully fiom the 
examples in tins article you have a good idea of the power of Tango. 

If you want to leam more about Tango go to the Pervasive web 
site. In addition to a lot of useful information, Pervasive wall lx 
putting out pre-releases of Tanogo2000 for the Mac that you can 
download and see all of the new features lor this next release. You 
aLso want to check out the URLs in the bibliography to see some of 
the other online Tango resource. 

Bibliography 

* <http://www.pervasive.com/products/tango/> — the main Pervasive 
Tango site, 

* <http://componentzone. pervasive,COm/> — an online source of 
Tango examples. 

* <http://www.tangozone.com/> — a site by Tango developers for 
Tango developers. 

* <ma i I to ^ango-ta I k ©pervasive, com ?su bject^s ubscri be> — Use this 
URL to subscribe to Tango talk the official Tango developers 
mailing list. 


Fignre 1 6. If <%NlJMRO W5> Action . 


Sites that use Tango; 


To handle the logged in correctly case, you arc going to set a 
variable of the type cookie that will indicate the u s er is logged in. 
We do dlls using an Assign action. Drag an Assign action under the 
If action. Click in die first column of the action window' and set the 


<http://www.jokes.com/> 

<http^/www ; theglobe.com/> 

<http://ww , jv,metrowerks.com/> 

< http ://l ists-apple.com/> Sl« 
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Introducing DCon 

By Matt Slot. Ambrosia Software 


Bugs Check In, Bit They Don't Check Out 

DCon, the"I>ebugging Console,” brings the joy of printfQ based 
debugging to the MacQS. Yes, that's right, I said joy. Sometimes 
you just need to examine a few key variables From a given function 
while your application is running. Under UNIX or DOS you would 
simply print those values to the console, but it hasn't been so easy 
for Mac programmers, Until now. 

Tliere are dot of sophisticated debugging tools on the market 
today, so why would anyone use 1980’s technology to debug a 
modern application? Probably l>ecause it’s si ill effective for finding 
some of the most elusive bugs. Wrap a troublesome piece of code 
with markers, and you can le!I If the application reaches one or both 
successfully. If you do this several times in a row (known as ‘binary 
partitioning"), you can narrow down memory corruption or 
crashing bugs to a given function or block of code. 

Listing J: 

Binary Partitioning 

Te st whether this function executes property by adding culls U> dprinllO before and 
after the body of ibe function At the end, return die result code indicating whether 
the function succeeded or why it Med. 

void S amp J. eFunc tian() 

I 

OSErr error * noErr: 

dprintft"S j art of SampleFunctiotiO\n") J 

errut = PossibleCrashlngFunctionO; 

if (error = noErr) 

error - AnotherCrash Injunction U ; 

(jprintf("End of SampleFunctionO ; %hd\rT. error); 

I 

Add lire header and libraries to your application, ilien call 
dprintfQ to record any sort of data to the DCon console window, a 
log hie, or both. As with printfQ. you use a string to format any 
combination of integers and text for output. There is even a 
dprintmemQ call to display arbitrary chunks of memory. 



figure 1. Floating DCon console window untb sample output. 


I he DCon console window is created by running the 
application, or installing the DConNub extension. The latter 
method creates a system-wide floating window that is always in 
front, so the user can switch applications and still watch debug 
output scroll by. This window can also be hidden and shown 
with just a hotkey. 

The DCon callbacks are interrupt safe and very fast. Since they 
are drawn to an always floating window, ifs easy to see the output 
even if the target application locks up the machine shortly after. 

You might wonder "Why not just use printfQ?”, but that 
requires you link against those large ANSI libraries and it's not 
interrupt-safe. The latter makes it unusable for those of who 
write device drivers, network callbacks, or even system patches. 

Others might suggest DebugStrQ instead, blit ids not as easy 
to format variable strings. It also lias one other drawback- 
dropping into Macsbug on a modern PowerMac is very slow, li 
must take over a whole monitor, change the depth, and swap the 
display — consuming a gtxid portion of a second with each 
change. This overhead may interfere with operations like sound 
or networking that are timing sensitive. 

'Hie last, and coolest, feature of DCon is that dprintf(} is safe 
lo call even if the DCon application or extension is not installed. 
H simply does nothing. You can build a single debug application 
that you can use internally and ship to your customers without 
worrying whether they have installed the debugger. If they find 
a problem, they can install the DCon application and send you 
hack a debug log. 

I've successfully used DCon to find elusive hugs in my 
network and sound code, bugs which are timing dependent or only 
surface after hours of extended use, I now instrument all my code 
with dprintfQ, reporting Ttxdbox error codes and asserting on 
invalid conditions, fve found DCon an invaluable addition to my 
debugging arsenal, because it really does kill hugs dead. 

m 


When he's not fighting the forces of evil, Matt Stoi writes 
games and utility software for the ultimate in Macintosh 
shareware, Ambrosia Software If that isn't enough, he s{.muis 
quality time with his wife feeling the baby kick amt shopping for 
adorable outfits. He welcomes yourjeedhack ami suggestions for 
baby names at fprefect^amhmsimurconi. You can also tisit bis 
homepage at hnpbwww amhrosimwxom/~jprefea r 
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Sophisticated Circuits Rebound! 2.0 
Automatically restarts crashed machines 

by Kelly Konechny 

Sometimes the .simplest ideas are the best. An idea like the 
one that Sophisticated Circuits had in Rebound!, a small device 
that detects a crash and then restarts the computer, is simple but 
extremely valuable. This simple, yet powerful idea has been 
built upon in Rebound! 2.0, which adds many new features that 
are bound to impress any webmaster or systems administrator 

Rebound! offers the certainty that your most important 
machines, web servers, file servers, or mail servers will run 
smoothly providing consistent service to your users. It 
maintains service by monitoring your computer invisibly, and 
detecting crashes when they happen. When a crash is 
detected the computer is restarted, and service is restored, all 
in minutes. 

Installing Rebound! 

installing Rebound! is a snap Rebound! consists of two 
parts, a small ADB device, and a control panel The ADB 
device, which resembles a dongle, plugs into the ADB port 
on the back of your Macintosh allowing the keyboard to be 
plugged into it And because of the introduction of USB with 
the i Mac s and the blue and white G3*s there is also a USB 
alternative to Rebound! called Kickoff, that is due to be 
released soon. The software installer for Rebound! places a 
small control panel in your system folder that provides you 
options for customizing RehoundPs actions. 

Configuring Rebound! 

Once you have finished installing Rebound! it begins 
monitoring your system for crashes. Rebound! will work 
quietly in the background, and you may never know that it’s 
there unless your system crashes, Rebound! \s default 
configuration will work with most systems but you may 
customize the settings in the Rebound! control panel. 

The ‘Enable Crash Detection’ button is checked which 
allows Rebound! to monitor your systems activity, and 
attempt a restart if it detects a crash. Rebound! works by 
updating an internal counter periodically in the Rebound! 
software which then communicates with the Rebound! 
hardware. Any time in which the counter is slopped. 
Rebound! sends the 'command-control-power oiV keystroke 
to restart the system. 

When setting the rime on the first sliding bar. Restart if 
system doesn’t respond 1 , consider that if this is a server unit 
it could encounter complex tasks which take time and 
Rebound! could interpret it as a system crash. The default 
setting of five minutes Is suitable, but if you know that the 
server is weighed down with users or heavy tasks, you 
should set this number higher. 


Time allowed for system restart 1 simply tells the 
Rebound! hardware how long to wait before starting to send 
events again to the software. If the system crashes again 
during the start up process, Rebound! will attempt to restart 
it again based on how many time you set it to try to restart 
on the Number of restart attempts' sliding bar. This setting 
should typically remain at one attempt, if your system 
requires more than one attempt to restart during the start up 
process, then there many be other problems to address. 

Rebound! can also monitor individual applications on 
your system. If you check off the 'Enable Application Crash 
Detection' box Rebound! will present you with options that 
enable the two types of crashes, unexpected quits, and 
application rimers. You can then choose how to respond Lo 
the crash by selecting either relaunch application, or 
restarting system. Rebound! also displays a list of the 
applications running along with rheir application timers. 



Figure L Applications that support Rebound! 

Apples bare IP 6.2- Apple Computer 
Communicate - Stalker Software 
LetlerRip Pro - Fog City Software 
Newsland- fmagina Inc. 

PageSentry - Maxum Development Inc. 

Quid Pro Quo - Social Engineering Inc. 

QuickDNS Pro Men & Mice 
SiteMonitor- Pacific Coast Software 
Web Server 4D- MDCJ Computer Services Inc. 
Webstar Siam ine 7 ech oologies 

Rebound! monitors application crashes because ifs 
possible that an application could crash leaving the rest of the 
system functioning properly. This could potentially put a 
system like a web server at risk of going down because if the 
web server software crashes, but Rebound! is still 
communicating with the system no action is taken. Rebound! 
can detect errors like, ‘Application Unexpectedly Quit’, and 
Other errors which affect only one application. Rebound! uses 
two methods to achieve this, one by using ‘Application 
Watchdog Timers' which can monitor any application's status, 
and tell if die application has encountered an unexpect quit. 
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The second method. ‘Application Timers' can detect situations 
where an application has only stalled without actually 
crashing, Based on a three-level fallback mechanism 
Rebound! can automatically re-launch a single failed 
application which leaves the operating system and other 
applications running. If the application fails to re-launch, 
Rebound! will activate a Finder restart, from the "Special* 
menu, and if the restart still fails Rebound! will send the restart 
command via die comm and-control-powder on keystroke. 

How to crash your system 

Once you've installed and configured Rebound! for your 
system how can you be sure that it will do it's job? In order 
to lest Rebound! simply hold down the command key and hit 
the power on key. A dialog box will appear with the V 
symbol in it. This is the Mac's built in debugger, with it open 
no other tasks are allowed to run, and in a few minutes 
Rebound! should restart the system. 

Methods of testing Rebound! are applications that 
purposely crash a system using a wide variety of system 
crashes. Crash Test is a small application thaL allows you to 
select the type of crash you want to test, and then crashes 
the system. Keep in mind that when doing any sort of crash 
testing on your system, you shouldn't have any files open as 
data can be lost. You may also warn to run disk first aid on 
the system to insure there aren’t any hidden problems caused 
by the crash testing. 

Advanced Rebound! Features 

Rebound! also offers features dial go above and beyond 
what you’d expect from this little device. Features like 
advanced logging, event messaging, advancements in 
automatic crash detection, recovery, and prevention, 

Advanced logging tracks both system and application 
activities. You can view a detailed log including the time, 
date, priority, and the type of activity. Activities that are 
logged include when an application was launched, when it 
was quit or automatically restarted, and when the system 
crashed and was restarted. These options give administrators 
the ability to know exactly when the system had a problem, 
and whai the outcome of the specific problem was. 

Accessing the log in some cases could be a lengthy 
Connection process to a remote server, so to avoid this 
viewing the log of system activities can be done through any 
browser. Rebound! comes with a WebStar API plug-in that 
allows the administrator to get an up lo the second view of 
the .system's activities. 

Being the first to know of a crash is of high value to any 
webmaster or system administrator. Rebound! can notify you 
via email if a server has encountered a problem. Rebound! 
sends the log file along with the high-priority email so you 
know exactly what the problem was. 


Of course the best way to keep a system running is to 
avoid a crash altogether. Rebound! allows the administrator to 
set scheduled restarts of the entire system which helps 
eliminate problems before they occur. Problems like memory 
fragmentation, can be a regular cause of crashing. By restarting 
the system regularly these problem are less likely to occur. 

Sc rip table Rebound! 

The nice thing about any great piece of software (anti 
hardware in this case) is the ability to script it. Rebound’s 
features can be controlled by AppleScript or any other GSA- 
compliant scripting language like Frontier, Scripting 
Rebound! is a valuable feature because different scripts earn Id 
be set up based on different events. And since several of 
ReboundFs features are accessible by Applescript the options 
are numerous. Creating an Applescript that changes any one 
or many of Rebound! s settings is simple. Place a Tell’ block 
in your script like this: 

tell application "Rebound 1 Extension" 
end tell 

When scripting Rebound! several of it s properties can 
be modified or read. The properties shown in figure 2 outline 
aspects of Rebound! that are scripfable. 



Figure 2 . 

System Crashes properties 

* sysTimerEnabled - Set to true to enable system crash 
detection 

* crashDetectionTimenut - Value of the “Restart if system 
doesn't respond” slider, in seconds 

* restart!nierval - Value of the “Time allowed for system to 
restart” slider, in seconds 

* restartCount - Value of the “Number of restart attempts” 
slider 


Application Crashes panel properties 

* appCrashDetectEnabied - Set to true to enable 
a[>plica tion erash detection 

* appTimersEnabled - Set to true to enable 
application timer monitoring 

* appRelaunchC ounr - Number to times to attempt to relaunch 
a crashed application before restarting the system 
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* appRelaundiWindow - interval (in seconds) of repeated 
application crashes which will cause Rebound! 
to restart the system 

Log Entry Priorities 

You can customize the priorities of Rebound!'s log 
entries by setting these properties. Possible values are 
‘emergency 1 (0), 'alert 4 (1), 'critical 1 (2), ‘err' (3), 'warning' 
(4), ‘notice’ (5), 'info 1 (6), 'debug 1 (7) and ‘disabled 1 (-1). 

* sysCrashRestartPriority (3) - “System crashes” log entries 

* appCrashPrioriiy (3) - “Application crashes/timed restart” 
log entries 

* appTimerExpirePriority (3) - “Application crashes/timed 
restart" log eriLrics 

» appRelaunchPriority (5) - “Application crashes/timed 
restart" log entries 

* appCrash Restart Priority (5) - “Application crashes/timed 
restart" log entries 

* appLaunchPriority (6) - “Application is launched or quit" 
log entries 

* appQui[Priority (6) quit" log entries - “Application is 
launched or quit* log entries 

* daemon La unehPriority (6) - “Rebound! Extension 

launches or quits" log entries 

* daemonQuitPriority (6) - “Rebound! Extension launches 
or quits" log entries 

* daemonQuitAEPriority (4) - Also “Rebound! Extension 
launches or quits," but reported when another application 
tells Rebound! to quit 

Relaunching open applications after crash 

* bookmarkingEnabled - Set to true to enable relaunching 
open applications after a crash 

Periodically restarting the system 

To set dm value, add up the values for each day of the 
week as follows: Sunday=i, Monday= 2, Tuesday=4, 
Wednesdays^, Thursday=10, Friday-32, Saturday-64. For 
example, to restart on Monday, Wednesday and Friday, set 
this value to 2+8+32=42. 

* autoRcstarLDays - Bit mask telling which days of the week to 
automatically restart the system (set to 0 to disable) 

* autoRestartTIme - Time of day at which to automatically 
restart the system 

In your script you can look at and modify the properties 
(Figure 2) by using Appleseript’s get and set commands. Fur 
example, to change the value of the “Restart if system doesn't 
respond* slider to ten minutes, place the following command 
in your tell block: 

set erasbUetectionTifoeaui to 600 


Application crash detection in Rebound! works by 
creating appTimers for every monitored application. Each 
application sets it's appTimer before it reaches zero, so that 
if that application crashes the appTimer will not be set and 
will reach zero. Then Rebound! kicks in and assumes that the 
application has crashed anti restarts the system. You may use 
Rebound! r s application crash detection to monitor databases, 
scripts or applications that you have written. Your 
application should send a tickle AppTimer Applescript 
command. The command looks like this: 

tickleAppTiraer 400 

Rebound! then creates a new appTimer for your custom 
application, script or database, and repeated commands will 
constantly update that timer. 

Whether it's a file server that has to be up 24/7 for 
production purposes, or if ii\s a web server that hosts your e- 
commerce site, Rebound! will keep the machine consistently 
running with minimum down time. And with features that 
notify you of an application crash or a system crash with a 
log attached of the events that happened seni via email, you 
can he sure Lhat you'll know at the first sign of trouble. With 
Rebound! installed your most important machines will be 
running smoothly, which allows you to concentrate more on 
other tasks aL hand. 



Figure 3. Picture of REBOUND! f attached )* 


Rebound! plugs into the bark of your Macintosh and 
allows for another ADB device to puss through. 

You can find out more about Rebound! and Kick-off! at 
Sophisticated Circuits web site at <http://www.sophisticated.com>. 

El 


Kelly Koneehny is ihe Publishing Systems CuordimiEoi; and Webmaster 
at Farm Business Communications in Winnipeg, Manitoba. Canada, 
Kelly am be found most days working on www ageanada cum , and he 
can be readied at kkonechny@flx.unitedgniin.ca. 
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PROGRAMMER'S 

BOOKSHELF 


By Paul H. Seizing, Switzerland 


Review: Cryptography 
and Network Security 


Principles and Practice, 2nd edition 


Cryptology is a topic more and more people in the IT 
business have to be familiar with, If you already know the? 
basics and only need a reference manual .so to speak, 
choosing the right book is easy; [Mcnezes et al. 1997k But if 
you’re looking for an introductory text book, you have an 
ordeal of choice. One book youll often see recommended is 
[Schneier 19961. In this article we're going to take a closer 
look at another one, namely the 2nd edition of Cryptography 
and Network Security: Principles and Practice [Stallings 19991- 

The Big Picture 

Cryptography and Network Security (CaNS for short) has 
been published by Prentice Hall and was written by William 
Stallings, an author with quite an impressive publication list 
(see <http://www.prenhalLcom/stallings/>), Besides, famous 
cryptographers like Xuejia Lai, Ron Kivest, Phi] Zimmermann 
and many others reviewed Stallings' treatment of their special 
fields. In my opinion, Lliis makes the book very trustworthy. 

Between the introduction and the appendix (for 
teachers); CaNS is organized in four parts; Conventional 
Encryption, Public-Key Encryption and Hash Functions, 
Network Security Practice, and System Security. The 
introduction discusses network security models and computer 
security threats, thereby motivating the remainder of the text. 

From ihe very beginning, it Ls obvious that CaNS is noi 
intended to be a popular-science book but rather for 
(prospective) scientists and engineers. 

Conventional Encryption 

The first part, chapters 2 to 5, deals with symmetric 
cryptography. Le. schemes in which the same key is used for 
both encryption and decrypt ion. Actually, the main focus is 
on so-called block ciphers while stream ciphers are hardly an 
issue. (There are two ways how to use block ciphers as 


stream ciphers, though, and Stallings explains both when he 
treats the four block-cipher modes of operation.) The math 
used in this part nmodular arithmetic, linear equations, 
matrieesn should be basic to most programmers. 

Chapters 2 St 3 treat the building blocks of both classical 
and modem symmetric algorithms and show how these are 
used within DBS, the Data Encryption Standard. With the 
exception of the one-time pad. the classical algorithms are 
nowadays insecure, but still interesting for more than just 
historical reasons. Chapter 3 ends with general design 
principles of and attacks on block ciphers, 1 find this to be 
useful to practitioners who have to decide on and implement 
an algorithm, not to hackers ;-) 

Unless interested in details of different algorithms 
currently in use, live reader can safely skip most of chapter 4. 
Nevertheless, the first section is important because it contains 
information about the Men-in-the-Middle attack, and the last 
section is a good summary of the rest of the chapter. 

Most of us don't really need to know how exactly 
encryption works. But if we use it, we beLter use it right. In 
chapter >, Stallings explains where and how symmetric 
schemes can be used in an internetwork, including the non¬ 
trivial task of key distribution. One problem in this context is 
generating good pseudo random numbers. Different 
approaches are mentioned, but only very briefly. 

Public-Key Encryption and Hash Functions 

The second part, chapters 6 to 10, deals w r ith functions that 
map variable-length data into a fixed-length value anti with 
asymmetric cryptography, i.e. schemes in which different keys 
are used for encryption and decryption. This part Ls more 
mathematical than Lite last as public-key cryptosystems are 
heavily based on number theory, the suhjeri of chapter 7. 
(Stallings only introduces what is necessary for understanding 
CaNS, If you're not familiar with number theory* I suggest you 
read this chapter before the 6th.) 


Paul is un EE student at the Swiss Federal Institute of Technology Zurich (FT117.) where he might spend another three years if he accepts the PhD. 
position offered to him. But as he feels like living in the IIS for some time, he's wondering wliether he should rather join a R&D department in Silicon 
Hills or Silicon Valley. While he's thinking about this, visit his homepage at htlp://www.stud.ee.elhz.cfo~pse vine/ 
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Starting with the principles of public-key cryptography, 
chapter 6 presents RSA, the RivesuShamir-Adleman algorithm, 
the Diffie-Hellman key-exchange protocol, and key- 
management issues in general. At the end of this chapter, there's 
a short section about elliptic-curve cryptography, a hot topic of 
growing importance, which I highly appreciated. 

Similar to chapters 3 & 4, chapter 8 first treats requirements 
and design principles of, as well as attacks on cryptographic 
hash functions and message authentication codes (key- 
dependent hash functions so to speak), and then chapter 9 
describes four concrete algorithms in detail: MD5, 5HA-1 T 
RIPKMD-I 6 O (that's what I call an acronym!), and HMAC. 

Chapter 10 concludes the second part with a discussion 
of authentication protocols and digital signatures. The former 
include such based on symmetric cryptography, the latter 
DSS, the Digital Signature Standard, 

Network Security Practice 

The chapters in the third part (11-14) can be consulted in 
any order the reader likes. The prerequisites have been covered 
in the first two pans. This part is a nice add-on to older, in terms 
of IT years, computer-network books that don't cover network 
security fin enough detail). It includes sections on Kerberos, 
X.509, PGP, S/MIMK, IPSec, SSL/OS, and SET. 

Kerberos and X.509 are for authentication purposes. PGP, 
Pretty Good Privacy, and S/MIME, Secure/Multipurpose Internet 
Mail Extensions, provide e-mail security, IPSec comprises the 
security features lhai have been defined for IPv6, but that can 
also be used with IPv4. (Those of you familiar with IP, the 
Internet Protocol, know that we're currently making the [slow] 
transition from IPv4 to IPv6.) SSL is Netscape's Secure Socket 
Layer which has become Transport Layer Security, an Internet 
standard. Finally, SET, Secure Electronic Transaction, is a 
specification initiated by MasterCard and Visa for credit-card 
payments over the internet. 

By carefully reading several of these case studies, one 
gets a good idea of the trade-offs (e.g., security vs. 
complexity) involved in the design of cryptographic 
protocols. This is supported by Stallings F clear and concise 
writing and his judicious use of figures and tables. 

System Security 

The last part, chapters 15 & 16, is very high-level and 
easy to understand. However, it only provides an overview 
and can't replace an in-depth (and more technical) treatment 
of the same topics. 

I was blown away by chapter 15. It is about intruders 
hackers and trackers) and malicious programs, especially 
viruses. The many risometimes ingen iousri ways of attacking a 
computer system and their countermeasures make for very 
exciting reading; look forward to a rainy Sunday! 


Chapter 16 is a short chapter about the principles and 
goals underlying firewalls. It ends with a section on so-called 
trusted systems and I tow these can he used to defend against 
trojan horses. 

Conclusion 

CaNS is a very good introduction to cryptography, 
enabling you to understand and discuss the security of 
practical cryptosystems (e.g., the Mac OS keychain). But if 
you intend to develop or consult on cryptosystems yourself, 
you need to know more about number and information 
theory (see the seminal [Shannon 1948J) than is covered by 
Stallings. The parts about network and system security are 
good, too, even though they might not be applied enough for 
some readers (e.g., system administrators). 

Every chapter ends with a set of non-trivia! problems 
(the solutions are not part of the hook). Some chapters 
additionally feature an appendix of their own, Tor example 
about ZIP's compression algorithm, the Birthday paradox, 
IPv4 and IPv6, etc. These appendices increase CaNS 6 
usefulness and are thus worth being studied. 

Finally, a five-page glossary and a one-page list of 
acronyms conclude this highly recommendabie book. 
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By Rich Morin and Doug McNutt 


The Well-Connected Mac 


Protocols, Plugs, Wires, 
and Waves 


Background 

Early Macintosh computers had very 
limited capabilities for communication. 
Over time, however, a number of 
interfaces have Ixrcn added to the Mac's 
repertoire. Current Macs can communicate 
via ADB, Airport. Audio. Ethernet (both 10 
and 100Base-T), FireWire, IrDA. LocalTalk, 
PC Card, PCI, SCSI, USB, and Video 
interfaces, to name just the mosi common. 

Obviously, the characteristics of 
these interfaces vary wildly. Most, but 
not all, arc digital. Most are carried by 
“serinl M cables, but some use parallel 
wiring, plug directly into the 
motherboard as cards, or communicate 
via wireless means such as infrared or 
radio waves. It is not surprising, 
therefore, that many Macintosh users 
(and even developers!) find themselves 
a bit confused at times. 

This article addresses this confusion 
by giving brief (and somewhat subjective) 
descriptions of each interface, along with 
references for further inquiry, it won't 
explain how to program the Mac for any 
of these interfaces, let alone how to 


design your own interface hardware, but it should let you know 
a lift about the strengths (and weaknesses) of each interface. 

Before gelling into the descriptions themselves, however, 
we need to cover some basic terms that will show up later in 
the article. Feel free to skip over this material, but be sure to 
come back to it if you start to get confused. The interfaces 
have no compelling "family tree”, and we will present them 
in roughly historical order. 

The first distinction of interest is that of ''analog" vs. 
“digital 1 '. All electronic interfaces are analog, in the sense that 
they use measurable voltages, currents, and other analog 
phenomena to communicate. Digital interfaces are 
distinguished, however, by the fact that their signals are 
interpreted solely as (sets of) bits. Thus, most audio and 
video interfaces are analog, but disk drives and such are 
always connected via digital inter faces. 

The next distinction has to do with topology. Busses 
connect two or more devices together; ADB, SCSI, and PCI arc 
all busses by this definition. "Point to point" interfaces, in 
contrast, lie pairs of devices together; most audio and video 
interfaces are used in this manner. Distinctions of this son can 
become fuzzy, however* when “hubs" are introduced. For 
instance, lOBase-T is an implementation of a bus (Ethernet), but 
it is based on a “hub and spoke” topology. 

Most interfaces use wires (in some form) to carry their signals. 
Airport and IrDA, however, use radio and infrared waves. Even in 
the wired domain, there are important distinctions to !>e made. 
"Semi" interfaces (c\g. ? ADB, FireWire, and Locafialk) send all of 
ihe data hits down a single wire; "parallel" interfaces (e.g., PCI and 
SCSI) use multiple wires, sending many bits at the same time. 

Got all that? Great! Now, let’s look at some interfaces... 
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Serial Ports 

Macintosh serial ports get used for a variety of purposes: 
modems, printers, and LocalTalk connections. Consequently, 
they are a bit different from the serial ports found on PCs and 
other computers. Nonetheless, they interoperate quite well 
with most standard serial devices, as long as the cabling is 
done properly. 

Serial ports on the Macintosh have always conformed to 
Radio Standard 422 CRS-422X which is a balanced-pair version 
of RS 232. Apple went a bit further, however, arranging its 
ports so that they could be connected to RS-232 devices using 
only wiring changes. Thus, the voltage applied to Apple’s RS- 
422 pairs ranges from +5 to -5 volts. This is a bit high, but it 
is still within the RS-422 specification It also allows an KS-232 
device to be connected between the negative transmitter line 
(TxD-) and ground. The negative receiver line (RxDO in the 
Apple port can be connected to an KS-232 transmitter if the 
positive receiver line (KxD+) is grounded. 

Also provided are two housekeeping c hannels, one in 
and one out. They are driven (single-ended, in RS-232 
fashion) from -5 to +5 volts. The RS-232 specification calls for 
two such channels each way. Consequently, there is a 
continuing question about whether to connect the wires to 
DTK or CTS. etc. The solution will forever depend on the 
connected device (e.g.. modem or printer) and its associated 
support software. One more wire is available for external 
synchronization of the port, though it is rarely used for that, 
It has been used for carrier detect with modems when a Mac 
is used to support dial-in services. 

The Mac 128k provided power for external devices (at +5 
and +12 volts) on its 9-pin connector. That feature was 
dropped with the Mac+ and all further Macs in order to use 
the mini-DIN 8 pin connector. Somewhere into the first 
RowerMacs, a special mini-DIN 9 connector was made 
available and power was restored for peripheral devices. The 
mini-DIN 9 socket will accept a mini-DIN 8 connector if 
power is not required, 

The Zilog 85,30 serial communications controller was 
used on early Macs and the technical manual for that chip 
remains the Apple standard. The 8530 has a feature which 
provides for mixing the dock wall) the serial NRZ data stream 
to create what Zilog calls FMO modulation, The effect is to 
move the frequency band occupied by the data away from 
zero frequency, which requires a direct connection, up to 
128 kHz, which can pass through transformers. 

ft is that modulation which makes AppleTalk 
connections possible between all Macs made prior to the 
iFruit. All one had La do was to connect the receive and 
transmit ports of a Mac to each other and, through a 
transformer to the receive and transmit pons of another Mac. 
tn fact, you could connect up to 32 transformers between 
Macs, using a two wire bus which needed only to he 
terminated at each end with 11.0 ohm resistors. 


It turns our that transformers are not always necessary 
for AppleTalk connections. If the devices to be connected all 
share a common power source and are not subject to large 
ground fluctuations you can connect two Macs using an 
Apple serial cable between printer ports, Ifs also possible to 
make an AppleTalk bus without transformers. 

Early Macs had to support video framing as a 
background task. Because the buffer for the printer port was 
guaranteed to be updated during video retrace periods, that 
port was chosen for use by AppleTalk software. In later 
machines, the modem port was also opened up for use. 

The serial-port version of AppleTalk, now known as 
LocalTalk, has now been largely supplanted by the Ethernet- 
based version, EtherTalk. Running at something like fifty 
times the speed, ElhcrTalk is definitely worth considering for 
any network that can use it. By looking around a bit. you 
should be able to find economical hubs, adaptors, etc. 
Data Co 111 Warehouse, in particular, carries a wide range of 
Ethernet hardware. 

SCSI 

The specification for the small computer system 
interface, SCSI, left a lot of room for variation in connectors: 
sadly, hardware vendors have taken far too much advantage 
of this ambiguity. Many of us have large boxes of SCSI 
cables, sporting assorted connectors: Blue Ribbon, DB-25, 
PB-50, etc, Apple has added at least two connector ty pes 
(DB-25 and HD 1-30) to this madness, 

Apple's additions are particularly egregious because, in 
an apparent effort to save space, they eliminate the separate 
ground paths specified by the SCSI standard. If you have 
trouble getting Apple SCSI to work reliably, this 
“simplification" may be part of the problem,With ingenuity 
and a bit of luck, however, some combination of cables will 
allow you to add an arbitrary device to your SCSI “chain". If 
the termination gods are feeling generous at the moment, all 
of tite devices on the chain may actually function! 

in any event, Apple has opted to move away from SCSI, 
so the question is becoming moot for many Apple users. 
FIDE is taking on the role of connecting disk drives; FireWire 
and USB are handling scanners, digital cameras, and other 
exotica. With luck. SCSI will soon be nothing but a fading, 
noxious memory for most of us. 

Apple employs SCSI as a single-ended parallel port in 
which each signal conductor is terminated w ith two resistors: 
220 ohms to +5 volts and 330 ohms to ground. Actually, these 
resistors are only used in “passive* terminators; "active” 
terminators, which can yield better reliability, emulate this 
setup using solid-state devices. 

In any event, the termination results in a quiescent 
potential of 3 volts and an effective termination resistance of 
132 ohms (which matches ribbon cable). Both ends of the 
chain should be terminated, but for short runs such as a 
single internal disk, terminating one end is sufficient. Data 
bits are sent In grounding a signal line with a transistor. 
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The 3-voIt terminator power must be supplied by at least 
one of the devices on the chain. The termination power is 
commonly supplied to the cable through a diode, which 
prevents multiple power supplies from “arguing” about the 
proper voltage. Consequently, the power supply with the 
highest voltage will end up supplying terminator power for 
the entire chain. 

Some devices have DIF switches or jumpers to control 
termination; others attempt to make the determination 
automatically at startup time. Unfortunately, they may they 
get it wrong if all devices aren’t powered up together. 

In addition to Lhe eight data conductors, there are 
several others which are used for device selection, 
synchronization, and other commands including arbitration 
(which allows any SCSI device to become a master, but is not 
used in the Mac OS), The data lines themselves are used to 
address devices, resulting in a limit of eight devices 
(numbered 0 through 7), The Macintosh is always unit seven. 

In asynchronous mode with acknowledge, the bus's 
clock speed is three MIIz. Because the data path uses eight 
bits in parallel, this translates to 24 megabits per second, In 
synchronous mode, this increases to five MHz (40 megabits 
per second). Although faster (e.g., SCSI-2) devices can he 
used on a slow bus, their speed will be limited to that of the 
host's SCSI interface. 

The SCSI specification has been extended with the 
introduction of Wide SCSI, SCSI-2, Fast SCSI, and Ultra SCSI. 
Wide can transfer as many as four bytes at a time. Fast SCSI 
runs at ten MHz. Unfortunately, Apple doesn't support any of 
ihese enhancements. 

Thus, you’re on your own Lu figure out how to connect 
a 68-pin Wide SCSI device to the Apple SCSI port. Generally, 
your best plan is to avoid such devices. If you have an 
application which really needs high-speed SCSI, you should 
purchase an add-in SCSI card, along with matching cables 
and terminators. 

ADB 

Although the Apple Desktop Bus is being replaced by 
the Universal Serial Bus (USB), there are still many millions 
of machines that use ADB, as well as a number of nice 
peripherals (e,g. t Kensington's great Thinking Mouse) that 
are not (yet) available in USB versions. In short, ADB is not 
going to disappear overnight. 

ADB has served Apple well. At ten kHz, it is plenty fast 
for keyboards, mice, and trackballs. The four-pin shielded 
mini-DIN connector seemed like a real step down from the 
9-pin latched D connector used by the Mat:! 28k, but it has 
proven sufficient for hot plugging and other insults. 

The ADB was the first desktop interconnection scheme 
to support a microprocessor in the peripheral devices. It was 
thus able to count pulses in the mouse and transmit only the 
r esult ing number to the host (considerably reducing tile 
n cede d ba ndwid t h) 


The main problem with ADB is not technical Instead, h 
lies in the fact that ADB is not an industry standard. By 
switching to USB, Apple gains access to large numbers of 
devices (at least, prospectively) at mass-market prices. This 
was never going to happen with ADB, which has always 
been seen as an Apple-only standard, 

Making matters worse, ADB even requires a license from 
Apple in order for vendors to use it. The license is 
inexpensive and is apparently intended only to let Apple 
control assignment of device types } but it may have been a 
deterrent, tn any case, ADB never became an industry 
standard. USB, in contrast, is already built into many millions 
of PCs; now all the PC vendors need to do is tell the users 
what it’s good for and how to access if. 

ADB uses only three wires (ground, power, and data), 
though a fourth (for starting up the computer) shares the 
cable. The data line is pulled up to five volts by the host 
computer through a resistor, allowing any device to transmit 
data by simply grounding the wire. 

Encoding is accomplished by dividing each bit period 
into thirds. Every bit begins with a downward transition, A 
rise to five volts at 1/3 of the bit time represents a zero and 
a rise at the 2/3 lime represents a one. A message consists of 
a .start bit T two to eight data bytes T and a stop bit. The 
computer supplies power at five volts (limited to 300 mA); 
this must be shared among all the connected devices. 

ADB devices have addresses and registers which can be 
read and written by the host computer. Up to 16 devices are 
assigned addresses at startup time, using device types 
assigned by Apple, ft is quite possible to have multiple 
devices (e.g, t a mouse and a trackball) that use the same type 
and address. 

Each ADB transaction begins with a command from the 
host, addressed to a device. There are four possibilities (talk, 
listen, reset, and flush) for each of the device registers. The 
host computer continually polls the “current" device (the one 
it has most recently talked with), Another device may 
request service by grounding the data line during the final 
stop bit of the message sequence. When the host computer 
detects a service request, it polls all connected ADB devices. 

Audio 

'lhe Power Mac comes with stereo audio connectors for 
input and output. The interna! representation of this data is CD 
quality (16 bits at 44,100 samples per second, supporting audio 
signals of up to 22 kHz), Although many audiophile purists say 
terrible things about CD-quality audio, most consumers find il to 
!>e quite adequate. In point of fact, so do we. 

Unfortunately, Apple does not provide any convenient 
digital audio paths, h is possible to attach digital audio 
devices (e.g., CD, MP3, or mini-Disc recorders) via SCSI or 
FireWire, and some Apple machines provide an internal 
digital audio/video interface, but consumer dev ices- cannot- 
attach to any of this directly. This is disappointing; look at 
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Sony's VAIO series to see a dramatically higher level of 
audio/video connectivity and support. 

Motherboard Busses 

Early expandable Macintosh systems used Texas 
Instrument s 10 MHz NuBus, a solid and well-designed bus 
that, unfortunately, never gained acceptance in the PC arena. 
Consequently, while Apple users simply plugged cards into 
available slots in their boxes. PC users had to fiddle with 
jumper settings, DMA vectors, and IRQ assignments. 

More recently, however, Apple has adopted the 
Peripheral Component Interconnect (PCI) bus, which seems 
likely to be the standard for both PCs and workstations for 
some time to come. Be a bit careful, however, when you 
refer to the PCI bus. There arc two available bus speeds 03, 
66 MHz) and two available data paths (32, 64 bit), 

Apple also uses the PC Card (aka PCMCIA) interface for 
its portable computers. Aside from noting that there are 
several types of PC Cards, in assorted thicknesses, we have 
no real reservations with the standard. It seems to be 
functional, overwhelmingly popular, and likely to he around 
for at least the next several years. 

Video 

Apple's early machines had video modulators which 
produced signals for American TV sets. This format - NTSC 
(National Television Standards Committee) video - has 
limitations which make it very unsuitable For use in high 
resolution computer displays. 

NTSC's horizontal resolution is limited to about 350 
"lines" (700 pixels); the vertical resolution is theoretically 
capable of around 500 pixels, hut many older sets only 
display about half that resolution. Even and odd horizontal 
rows of pixels are alternately displayed (interlaced), often 
producing an annoying jitter Finally, some repetitive 
patterns (e.g.. stripes) conflict with the phase encoding used 
lor color information, yielding obnoxious artifacts. 

Video monitors built especially for computers are not 
interlaced. They also have much higher bandwidth, and 
hence pixel count, than TV sets. As they have improved, 
however, a plethora of horizontal and vertical scan rates have 
appeared in the marketplace. Meaningful standards were 
never developed and compatibility nearly became impossible. 

Apple attempted to deal with this problem by grounding 
selected leads in the video cable. Three pins were dedicated 
to this, supporting seven possible monitor types and a "no 
monitor connected" condition. Seven monitor types were not 
enough, however, so diodes were added to supply more 
detectable states. See Apple Developer Note HW 30 for an 
engaging account of this rework. 

In the Wintd world. a multisync” monitors appeared to 
deal with this problem. In principle, these monitors sense the 


work. In any case, these monitors clo not supply the cable 
encodings desired by Apple computers. We have seen both 
partial and universal adapters which allows switching among 
some or all possible settings. Although these can be useful, 
they are not guaranteed to work in all situations, 

Apple's latest monitor, the Apple Cinema Display (ACD), 
seems to be on a better track. Until the ACD, all flat panel 
monitors on the market were configured for connection to 
the computer's video output pan. Consequently, the image 
was converted from digital to analog in the computer and 
then back to digital form in the monitor. This adds cost at 
both ends and reduces the accuracy of the displayed image. 

The ACD does none of this; instead, it connects the 
display screen digitally to the computer. The result is that the 
update rate can be vastly reduced - to ten Hz or less - if the 
picture is static, if a pixel doesn't change, after all, there’s no 
need to update it! Also, because digital signals are being sent 
over the cable, reflections and other artifacts of analog 
transmission can be eliminated. 

It remains to be seen, however, whether other vendors 
will accept Apple's interface standard. At some level, it 
doesn't matter; Apple's interface card is PCI-based, so iL 
should work on most desktop PCs. As other busses appear, 
new interface cards can be developed. On the other hand, 
some display vendors might choose to go directly to 
FireWire, making the interlace card unnecessary and 
allowing a far larger number of monitors. 

Of course, if every pixel on the display screen needs to 
change at once, the instantaneous bandwidth can become 
enormous. The ACD’s 1,6 million pixels, at 24 bits each, 
comprise some 40 megabits of data. A FireWire connection, 
at 400 Mbps, could only handle ten such full-screen refreshes 
each second. Still, for many purposes, this would be more 
than adequate. 

EIDE 

FIDE (Enhanced Integrated Device Electronics) disk 
drives are inexpensive, often less than half the cost of 
similarly-sized SCSI drives. Pan of this comes horn simplicity; 
unlike SCSI drives, FIDE drives don't have built-in 
controllers. The computer must therefore tell the EIDE drive 
which cylinder, head, and sector to address, how to handle 
bad blocks, and mure. 

EIDE drives are also inexpensive, however, because of 
market considerations. Given current disk sizes (e g.. IBM's 
36 GB DeskStar), one or tw'o EIDE drives are likely to meet 
the needs of most desktop machines. So, EIDE has become 
the interface of choice for low-end service; SCSI is reserved 
for high-performance applications, servers, etc. 
Consequently, disk vendors no longer manufacture 
moderate-performance (and thus, economical) SCSI drives. 

Unfortunately, HIDE'S terrible distance (18”) and fanout 


syndirnmillion si gnals emitt ed from llie con 
appropriately. In practice, however, not all combinations 


(2) limitations mean that it c a nnot be used 
devices. SCSI, the current standard for this role, isn't all that 
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much better; the cables are awkward and very poorly 
standardized, the distance (20') and Fanout (7) are limiting, 
and hot plugging is generally a risky business. 

The HIDE bus is usually implemented with a 40-conductor 
ribbon wire and is limited to use inside the case of a computer. 
There is no provision for terminating the transmission path to 
eliminate reflections. Only very simple addressing (limited to 
two devices) is available and most of the disk management 
issues must be handled by the host computer. 

Although USB is being proposed as an alternative to 
HIDE and SCSI, it is simply too slow to serve the needs of 
high-speed devices. We are therefore hoping that IEEE-1394 
will answer the need for economical and flexible 
connectivity to block-oriented devices, 

Ethernet 

Two Ethernet cabling methods are currently in common 
use. 10Base-2 uses a single co-axial cable, daisy-chained 
l >e tween the systems on the network and terminated at both 
ends by a 50-ohm resistor 10 and 100Base-T, in contrast, 
employ twisted-pair cabling between hast machines and a 
central “hub". 

Although both 10Base-2 and iOBase-T are specified as 
ten MHz networking technologies, this doesn’t tell the whole 
story. If more than one Ethernet interface is trying to send 
data, the possible throughput goes down by about half 
(because of packet collisions, etc.) If higher-level protocols 
(e.g., NFS) react poorly to broken packets, the bandwidth 
can degrade even further, 

Bandwidth also interacts somewhat with network topology. 
Because l DBase-2 uses a single coaxial cable for everything, 
only one packet can be "in transit" at a given time. Simple 
lOBase-T implementations (much like AirPort, described below) 
emulate this behavior, propagating the same limitations into Lite 
new (hub and spoke) cabling topology. 

Fancier implementations (e.g„ switching hubs) take 
advantage of the fact thaL a given packet only needs to travel 
along two of [lie spokes. Thus, A can send packets to B while C 
is sending packets to D, As the number of nodes increases, this 
optimization can improve performance dramatically. If you have 
a busy network and aren’t using switching hubs, you aren’t 
getting anything like full performance from your wiring! 

When installing or upgrading a twisted-pair network, 
pay dose attention to the type of cable you employ. 
Although lOBase-T works fine with Category-3 cable, the 
cost difference for Cat-5 is insignificant when compared to 
the installation cost, etc. When you consider that Cat-5 can 
be used for 100Base-T (and perhaps faster) systems, the 
choice is pretty dear. 

Do not, in any case, attempt to use ordinary telephone 
cable (or other wiring you may have available) for your 
Ethernet rims. Cat-5 cable is state of the art stuff, employing 
carefully-controlled insulation, twist rates, etc. As a result, 
both crosstalk (between the pairs) and radiation (to outside 
receivers) is minimized. 


You can, however, get away with running two lOBase-T 
connections over a single cable?. Both Cat-3 and -5 have four 
pairs, but 1 DBase-T only needs two of them. 100Base-T 
requires all four pairs, however, so this may not be a good 
long-term solution. 

If, when you were wiring up your network, you had the 
wisdom to use Cat-5 cable, you are in a great position to 
Upgrade to 100Base-T, Because of the hub-amkspoke 
topology, all you need to do is stuff a 100Base-T hub 
alongside your existing lOBase-T hub in rhe wiring closet (or 
wherever :-), Hook the machines with fast interfaces (e.g., 
iMacs) onto the new network; leave the slow ones on the 
lUBase-T network (or add 100Base-T cards)... 

Looking ahead, a technology called Gigabit Ethernet is 
just around the corner. A version (IQOOBase-T) is being made 
to work with Cat-5 cable, so again you can will be able to 
upgrade widiout rewiring your network, Apple hasn’t bought 
into Gigabit Ethernet yet, but we strongly suspect that they 
will, as soon as prices drop and availability increases. 

IrI>A 

The Infrared Data Association standard (IrDA) is a serial 
communication protocol which is built on the conventions of 
Radio Standard 232 (RS-232), bin uses infrared light rather 
than electrical connections. Where RS-232 is a nonrelurn-to- 
zero (NRZ) format, IrDA uses short pulses of light. A one is 
represented by a pulse 3/16 of a bit period long and a zero 
is represented by the absence of a pulse at a specified time. 

The communication channel is point to point, with no 
broadcast capability. Each point must have one IR transmitter 
(usually a light emitting diode (LED)) and a detector (usually 
a phototransistor). These devices arc commonly installed as 
a pair, using a single package which includes a driver and 
preamplifier. Sometimes another chip is used to convert NRZ 
into the short pulses for transmission and to convert them 
back to NRZ for use by the serial port of a microprocessor. 

The IrDA specification calls for a maximum path of a 
meter or so in the presence of normal room illumination, but 
there is no reason that longer ranges cannot be obtained with 
lenses. IrDA does not require careful pointing of 
communicating devices toward one another. Megabit per 
second speeds are possible; the lowest of the common RS- 
232 speeds is 2400 baud. 

It is important not to confuse IrDA with the common IR 
television control, which uses a higher frequency carrier to 
modulate the light and thus achieve much longer range in 
rhe presence of room illumination. 

USB 

Intel's Universal Serial Bus (USB) is designed as a multi¬ 
point replacement for RS-232, allowing up to 127 devices to 
be connected. In the Apple world, it is also a replacement for 
the Apple Desktop Bus. Cabling consists of a (two conductor, 
twisted) shielded pair for bi-directional data, plus two 
heavier wires for five-volt power and ground. USB supports 
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two speeds, 1.5 MHz and 12 MHz, which can exist together 
on the same bus. Wiring for L5 MHz need not be shielded; 
neither speed requires termination, 

Two new connectors have been developed for use with 
USB. One has four pins in a row and is used for connecting 
devices to hubs. The other has a square shape and is used 
for connecting hubs to computers or other hubs. You may 
never see the square shaped one, because hubs often have 
captive cables or are built into things like keyboards. 

The overall connection scheme is described as “tiered 
huh and spoke”. The tier starts with a hub to which a few 
devices can be connected. When the top level runs out of 
connector space, another hub can be added (much as you 
would plug extension cords into a power outlet). Apple's 
USB keyboard is a hub, typically used to support a mouse. 

The hubs need to have some intelligence, because they 
are required to sense the addition of a device to an operating 
bus and inform die host. Actually, die huh will not apply bus 
power to the device until the host has assigned an address. 
The bus also must recognize high speed communication by 
the host and not send it out over unshielded wires or to 
devices it knows can handle only the lower speed. 

USB packets consist of a synchronization pattern, a 
frame identifier, a device address of seven bits (128 devices), 
a frame number, up to 1023 bytes of data, and a cyclic 
redundancy check (CRC) code. 

The digital encoding format is “non return to zero 
inverted - mark” (NRZM) ? in which a change in the bit stream 
as transmitted represents a zero, while no change represents 
a one, This scheme uses minimal bandwidth, but it can be 
fouled up by a string of one bits which produce no 
transitions for synchronizing clocks. The solution is bit 
stuffing, in which the transmitter counts consecutive ones 
and inserts a zero after the sixth one. The receiver is charged 
with reversing the process. 

USD's signal amplitude is low: 0 A volts differential 
centered at 175 volts DC. As busses mature and electronic 
devices improve, lower voltages and currents can be used, 
requiring less signal power and creating less interference. 
Thus, serial communications have moved from current-loop 
devices (e.g. T old teletypes) through the 12V R5-232 standard 
to USD’s 175 volts. 

Power management on the USB can be problematical. 
The hub is supposed to supply power for the bus, but 
individual devices (if sufficiently power-hungry) or 
collections of devices (if sufficiently numerous) can overtax 
the hub's capabilities. As a result, the supply voltage can be 
depressed to the point that the entire bus fails to operate. 

Current limiting by the hub helps, but this is not a 
perfect solution. Self-powered hubs, which do not draw 
excessive power from the host computer, can also help. 
Fundamentally, however, it is up to users to keep track of the 
load they are demanding of their hubs, jus Las they would for 
electrical devices on a common circuit hreaker. 


Devices which derive their own power from another 
source must still connect to bus power, because of the 
signaling features involved with connection to a hot bus 
(high- and low-speed devices are identified by details of the 
power connection). A device which is plugged into the bus, 
but is otherwise in an off state, must still provide information 
to the host. 

The USB protocol allows for priority handling of a 
channel. This is necessary for time-sensitive data, such as 
digitized audio. Priority channels are isochronous (allowing 
guaranteed real-time performance) and unidirectional. 
Blocked channels are bi-directional and may or may not 
include error checking- 

Bbcked data can be given a back seat by software, up 
to a limit in which Lhe priority channel uses all available 
bandwidth. It is interesting that the G4 will provide two USB 
channels to avoid this sort of saturation. 

Converters (e.g,, to ADB, Ethernet, LocalTalk, and SCSI) 
are conceivable and most are already available. These often 
exhibit speed mismatches, however, and should be 
considered only as temporary solutions. 

IEEE--1394 

IEEE-1394 is a high-speed serial connection, developed 
by Apple and later codified by the IEEE specification. Apple 
markets the interface as FireWire; Sony markets it as i.LINK. 
tt currently runs from 12.5 to 400 Mb/sec and higher speeds 
are forthcoming. 

FireWire has been adopted for real-time video use hy 
camera manufacturers and it is rapidly becoming the 
interconnection means of choice for external disk drives for 
which cabling is a consideration. Dedicated game computers 
(e.g, 5 by Nintendo) have been a testing ground for FireWire 
concepts and hardware. 

The FireWire cable consists of two twisted and shielded 
pairs and two power wires fitted into a special connector. 
There are no terminators - ai least none that users have to 
be concerned with, FireWire devices need to have two 
connectors, one for the cable to a source and another for 
connecting the next device to the chain. The pins in the 
connectors are designed to allow hot plugging without 
damage even if power is on. Of course, interrupting a chain 
to add another device will affect the remainder of the chain. 
Repeaters, splitters, and bridges allow for free-form chaining 
of devices in stars and chains. 

Unlike SCSI, FireWire arrived on the scene with a 
standardized connector, so we have some hope of reasonable 
long-term sanity in this matter. Unfortunately, the “standard” 
FireWire connector lias already been compromised: video 
cameras use a 4-wire version of the cable with no power lines 
and you may need an adapter cable. Sigh, 

The FireWire protocol is a peer-to-peer system which 
has the potential of connect i ng computers to eaeh-other tts^r 
high-speed AppleTalk net, but no hardware is yet available 
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to support the feature. Work is also being done on an IP 
definition for FireWire and JIni (Sun's Java-based 
communication protocol) also seems like an interesting 
possibility; stay tuned*.. 

Because FireWire is a peer-to-peer system, the 
distinct ion between computers and peripherals can become 
a bit blurry. It is conceivable, for instance, that a video 
camera could Lake control of a Macintosh, telling it how u> 
process and store incoming data. Provision is made for 
asynchronous and isochronous communication for bulk 
transfers and time-critical one-way transfers, respectively, in 
a manner quite like the USB (but much faster 

AirPort 

Apple's AirPort system is based on Lucent's WaveLAN 
implementation of the IEEE 802,11 Direct Sequence Spread 
Spectrum (DSSS) radio standard in the 2.4 GHz band. It is 
currently being shipped with the iBook, but its promise 
extends far beyond that use. Many sites may soon be able to 
run their entire networks on AirPort, avoiding the need to 
run cables. 

Nonetheless, AirPort has some significant limitations. 
The primary one is speed: ten Mbps was fine for the 9G’s, but 
the clienL-server and multimedia needs of the coming decade 
will demand 100 Mbps (or even faster) links. Worse, like 
simple Ethernet hubs, each AirPort hub can only handle one 
packet at a time. So T the hub's speed is divided by the 
number of currently active sessions. 

Although more hubs can be added, logistics may 
become a problem. Wired networks have no problem with 
tightly-packed sets of offices; the signals only go where the 
wires allow. Radio networks, in contrast, can have problems 
with distances, shielding, interference, asymmetric 
communication paths, etc. 

We are thus concerned that AirPort may not handle large 
sites (e.g. t offices and schools) as welt as users might wish. 
Until a few positive reports of large-scale installations have 
come in, we would advise users to be cautious about 
building their plans around this technology, 

AirPort uses direct sequence modulation spread 
spectrum technology. This technique lets users share a 
common frequency band without significant interference, 
though the “noise floor 1 ’ does rise as more transmitters 
become active. 

Specifically, each transmitter encodes its message, using 
a 40-bit, pseudo-random code, Receivers correlate the 
incoming data stream with a copy of a specific, desired code. 
This allows them to suppress other codes, which (are 
supposed to) appear like random noise. The packets are also 
encrypted and sequenced, making interception and spoofing 
very difficult. 

Lucent contends that this makes AirPort as secure as a 
wire d network; dial is. file degree of diffic u lt y - one would 
have in cracking it is equivalent to the difficulty of gaining 


access to a physical network. We would respond that some 
physical networks are far better protected than others, so the 
comparison is bound to be a bit sketchy, in any event, we 
wouldn't advise you to rely on AirPort’s security against nosy 
three-letter agencies or well-heeled competitors. 

There is also a question regarding the “noise floor”. 
Airport's encoding technique is known as code division 
multiple access (CDMA). CDMA allows convenient and 
informal bandwidth sharing (without control of a telephone 
company switching channels or an FCC assigning 
frequencies), but it does not create bandwidth where there 
was none before. 

As more users enter the unlicensed band (and they need 
not be AirPort users), the apparent noise level in a given 
locale will increase and the band can saturate. We simply 
cannot predict when problems wall arise without tire large 
scale test of millions of links in an environment set up by 
average users. Stand by. 

Dodo Birds 

We have ignored a few connections which were rarely 
used or have fallen into disuse; here are some scattered 
comments which you may find interesting. 

There were several implementations of a Processor 
Direct Slot (PDS). which appeared in the SE and the II si 
among other less expensive Macs. They are a simple 
connection to the pins of the microprocessor, with Llie 
additions of power and ground lines, Ethernet ports, 
additional video, and modems were available on the market. 

A special audio-visual interface connection has been 
provided in some Macs — especially those with built in 
support for digital signal processors (DSP). 11 was usually 
used in conjunction with a NuRus or PCI card to supply high 
quality audio. 

Early Macs had a special 19-pin subminiature D 
connector, for use with external floppy drives. 

A specialized version of die serial port, the geoport, was 
briefly used for connection to telephone lines with only a 
certified data access arrangement (DAA) connection. Using 
DSP, it was possible to program the functions of an external 
modem in software. 

In Closing 

Apple's early connection strategies were dominated by 
the need to minimize hardware components (and thus, 
production costs). So, for instance, none of the early Macs 
used Direct Memory Access (DMA) chips, relying instead on 
the CPU to transfer data between devices and rnamory. As 
interface chips have become more economical, however, 
Apple has moved to more flexible and powerful interfaces. 

Apple has also started to adopt and promote Industry 
standards, a move which we greatly applaud Although you may 
still need-ro-d ownload drivers fro m a web site, many o f-thtrnrw 
IEEE 1394, PC card, PCI bus, and USB devices should work with 
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Interface Name 

A/D, 

S/P 

Physical 

Connection 

Bus 

Topology 

Distance(ft); 
Speed (Mbps) 

Fanout 

Limit 

Common and Typical Uses 

1 DBase-2 

D, S 

cable 

shared bus 

600;10 

none 

med-speed networking 

lOBase-T 

D.S 

cable 

hub/spoke 

300; 10 

none 

med-speed networking 

100Base-T 

D, S 

cable 

hub/spoke 

300; 100 

none 

high-speed networking 

ADB 

D.S 

cable 

shared bus 

typ. 10; 0.01 

16 

low-speed serial devices 

AirPort 

D, S 

radio 

shared bus 

150;11 

none 

med-speed networking 

Audio 

A, S 

cable 

single link 

typ. 10; 22 kHz 

none 

powered speakers, etc. 

EIDE 

D, P 

cable 

shared bus 

1-5; 32-100 

2 

hard disk drives 

FireWire 

D, P 

cable, socket 

hub/spoke 

13; 12.5-400 

63 

block devices 

IrDA 

D.S 

infrared 

single link 

3; 4 

1 

med-speed serial devices 

LocalTalk 

D, S 

cable 

shared bus 

1000; 0.2 

254 

low-speed networking 

NuBus 

D, P 

socket 

shared bus 

0; 300 

typ. 3-6 

interface cards 

PC Card 

D,P 

socket 

shared bus 

0; 4 - 1000 

typ, 1-4 

interface cards 

PCI 

D, P 

socket 

shared bus 

0; 500 - 2000 

typ. 3-6 

interface cards 

RS-422 

D.S 

cable 

single link 

3000; 0.2 

1 

low-speed serial devices 

SCSI 

D, P 

cable 

shared bus 

20-60; 80-600 

7 

block devices 

USB 

D.S 

cable 

hub/spoke 

16; 1,5- 12 

127 

med-speed serial devices 

Video 

A, P 

cable 

single link 

typ. 10; varies 

typ-1 

visual displays 


Macs, This should increase users' options in add-on peripherals, 
while decreasing the cost of such additions. 

Apple's lO Kit promises to add valuable features (e.g., 
strong multimedia support and hot-plugging) to the 
Mach/liSD underpinnings of Mac OS X. Tims, users with 
strong interests and needs for fancy I/O should keep a close 
eye on Mac OS X dev elopments over the coming year, 

Note: many of the figures in the table above vary with 
implementations, Consequently, they are intended only for rough 
comparisons, for specific information, contact the vendotfs). 

References and Links 

• AirPort 

<http://www.apple.com/ai rport> 

<http://www.apple.com/ibook/airport, html> 

<http://www.wavelan.com/> 

• Ethernet 

<http://www.ganymedesoftware.com/html/ethemet.htm> 

<http://www.gigabit-ethernet.org/> 

• IEEE-1394 (aka FireWire, i.LINK) 
<http://developer.apple.com/dev/firewire> 

<http://www.1394ta.org> 


<http://www.adaptec.com/technology/briefs/1394dif.htnil> 

<http://www.skipstone.com/compcon.html> 

• IrDA (Infrared Data Association) 

<ftp://irda.org> 

<http://www.irda.org> 

• LocalTalk 

<http://www.yale.edu/macguicte/Trouble/Localtalk, htmt> 

• PC Card (aka PCMCIA) 
<http://www.pc-card.com/pccardstandard.htm> 

<http://www.pcmcia.org> 

• PCI (Peripheral Component Interconnect) 

<http://www.pcisig.com> 

• USB (Universal Serial Bus) 

<http://www.apple.com/usb/> 

<http://www.ariston.com> 

<http://www.themacintoshguy.com/lists/MacUSBFAQ.shtml> 
<http://www.usb.org/> wi 
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MACTECH 



by Jeff elites <online@mactecb.com> 


Small Networks, Part 2 


Last month we started looking into some resources that 
can help you in setting up a small network, such as a home 
network to connect a few computers and printers. We found 
out that you can often cut your expenses by using an old 
Macintosh in place of new dedicated hardware, in this case 
to let you network a non-network printer, or expose a 
LocalTalk printer to an Ethernet network. Not only did we 
save some cash by using an old Mac, but also we made it 
possible to print from Mac OS X Server on a Blue and White 
G3, despite the limited connectivity options that platform 
currently supports. This month we re going to see how to use 
a single IP address to connect multiple machines to the 
outside world, again using an older Mac to do the real work. 

Learning to Share: Network Address Translation 

IPs a pretty common problem — you only have one IP 
address available, 3>ui now you have more than one 
computer. So, you have to decide which one gets to use the 
modem, DSL line, or cable modem, or else you end up 
switching off and having to do a lot of plugging and 
unplugging of cables. Although it seems as though it 
shouldn’t be possible, you actually can let all of your 
computers access the outside world at once through this 
single public IP address, thanks to a protocol known as 
Network Address Translation (NAT). In a nutshell, yon assign 
arbitrary "private” TP addresses to the machines on your local 
network, and all communication to the outside world goes 
through a gateway machine (which can be a computer or a 
dedicated hardware device), which iranslates the source 
address in the header of the outgoing packets to your single 
public IP address, and it makes a note of this. Then, it 
reverses the process on incoming reply packets, so that they 
arrive at the proper local machine. 

NAT is a capability built into most firewall products, and 
there are hardware devices which can act essentially as black 
boxes and do NAT for you, such as Sonic WALL, ReadleNePs 
firewall routers, and Macsense’s XRouter. These devices tend to 
be simple to set up and use, but are overkill if you just want to 

share an IP address- they are design ed to clo much more than 

just NAT, and their prices reflect tills, A software-based 
approach is more economical, and it continues my theme of 


taking advantage of your legacy Macs. Both Vicomsoft and 
Sustainable Soft works have software solutions which perform 
NAT, Vicomsoft has several different products which include 
this along with their other functionality, but I chose IPNetRouter 
from Sustainable Soft works: there is no limit imposed on the 
number of computers you can connect through a single 
gateway, and it is low-cost (it is priced at $89), in part because 
it is simpler and a little more do-it-yourself. Also, there is a 50% 
educational discount available. I’m going to focus on 
IPNctRouter here, but you may want to check out the 
competition (both software- and hardware-based) for yourself. 

SortkWALL 

<http;//www.sonfCwal!.com/> 

BeadleNet 

<http://www.beadleneUom/> 

Macsense XRouter 

<httpi//www + macsensetech,com/Produrt/mihl20.html> 

Vicomsoft 

<http://www.vicomsoft.com/> 

Sustainable Softworks 
<http://www.sustworks.com/> 

Although IPNetRouter can seem a bit cryptic at first, if 
you just warn lo do NAT there are dear instructions on the 
company's web site, and you'll be up and running in just a 
few- minutes. Your gateway machine can use either one or 
two Ethernet cards, and there are insiructions on how to set 
up either configuration. The two-card setup is conceptually 
easier to understand, and offers a bit more security: one card 
connects to your local network and the other connects to the 
outside, so no information about your internal network 
configuration can leak to the outside world without going 
through IPNetRouter. Ethernet cards are cheap, so you may 
want to opt for this setup. 

Getting Started with IPNetRouter 

<http://www.sustworks.cQrn/produas/ipnr/gettingstarted/Guide.htm!> 
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This brings up another benefit of NAT: your gateway 
machine acts in part as a firewall, hiding your internal 
network from the outside world. In fact, from the outside it 
will appear as though there is only a single computer 
involved. This, in itself, makes it difficult to break into your 
internal computers; your private LAN can access the public 
internet, but not the other way around. If you want to go a 
little further and add some additional security measures, 
Sustainable Softworks has a page entitled Building Your Own 
Low Cost Firewall which will help you set up IPNetRouter for 
this. Finally, you can do almost the opposite, and “punch a 
hole" in your configuration to allow, for instance, a web 
server to operate from inside of your network. To do this, 
you set up IPNetRouter to do inboundpon mapping, which 
routes all traffic destined for a particular purl aL your public 
IP address to a particular port on a particular machine on 
your Internal network. This allows machines on the public 
internet to initiate connections to your internal web server; 
they think they are connecting to, say, port 80 of your 
gateway machine, but really they are being served web pages 
from port 80 (or another port of your choosing) of in internal 
machine. You 11 probably need to do similar port mapping to 
use the QuickTime Streaming Server (but client machines can 
receive streaming QuickTime 4 content without any special 
configuration — support for this is built-in). 

Building Your Own Low Cost Firewall 

<http;//www,sustworksxom/produas/ipnr/gettingstarted/firewall.html> 

Port Mapping 

<http://www.sustworks f com/products/fpnr/gettingstartedy 

port_mapping.html> 

So, for less than $90 I can connect multiple computers to 
the internet, and set up firewall protection for a web server. 
That’s not bad, and best of all, it’s fast. In my home setup, 
I'm using a PowerMac 7500/150 as my gateway, and there's 
no noticeable slowdown compared to when my internal Mac 
is connected directly to my DSL line. Part of the reason that 
IPNetRouter is fast is that it is Open Transport native (in fact, 
most of its capabilities are built into Open Transport already, 
and IPNetRouter just provides a way to configure them). But 
you also have to remember that this isn’t a computationally 
intensive task — 1 believe that Cisco routers still use 68K- 
based processors. So even an old 68K Mac should give pretty 
good performance. 

The pages mentioned above do a pretty good job of 
introducing you to concepts such as NAT, firewalls, and port 
mapping* You can get some more information on NAT from 
the KnowIedgeShare section of Vicomsoft’s site, or you can 
go directly to the RFCs and get the details. 


Vicomsoft KnowIedgeShare: Network Address Translation 
<http://www.vicomsoft.com/knowledge/reference/nat.htmI> 
RFC1631 - The IP Network Address Translator (NAT) 
<http://www.faqs.org/ffcs/rfc1631 .html> 

RFC2663 - IP Network Address Translator (NAT) Terminology 
and Considerations 

<http://www.faqs.org/rfcs/rfc2663.html> 

So, again we’ve found a strategy that lets us use a spare 
Macintosh to save us the expense of buying new hardware to 
set up our network, adding IP sharing to our bag of tricks to 
go along with the printer sharing techniques we learned last 
month* Also, we’ve again solved a problem that developers 
will be especially likely to face: even if you plan to use only 
a single computer, if you are using Mac OS X Server then you 
currently need a second TP address in order to access the 
internet from the Blue Box. With a NAT setup this is no 
longer a problem, and you can use last month's printing trick 
at the same time by running Apple's LocalTafk Bridge on 
your gateway along with IPNetRouter — they seem to play 
well together. 

As a final note, when you run into snags you should 
check out the Three Macs and a Printer web site, which 
contains a wealth of information about setting up a small 
network, and explains everything in simple terms. It covers 
many topics that I have not been able to touch upon, and if 
has recently settled in to its very own domain. 

Three Macs & a Printer 

<http://www.threemacs.com/network/index.html> 

When you get tired of connecting everything together, 
take a gander at the other links available from the MacTech 
Online web pages at <http://www.mactech.com/online/>. ESQ 
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REALbasic 



The visual, object-oriented 
BASIC development 
environment for Macintosh* 


Apple 

Design 

Award 


Best New Product 


1 , 

Apple 


Design 


Award 


mr 


Most Innovative 


Apple 

Design 

Award 


Best Macintosh 
User Experience 


MannrM 

«« 


Our award-winning IDE is the most advanced BASIC development tool available for the 
Macintosh. Build compiled applications faster and easier. It's easy enough for beginners and 
powerful enough for developers to use. 


• 100% Object-Oriented BASIC with classes, constructors, 
destructors, inheritance, properties, methods, virtual 
methods, multi-threading, and automatic garbage 
collection — even more object-oriented than C++! 

• Build your applications on the Macintosh and deliver on 
both Macintosh (68k and PowerPC) and Windows (95, 
98 and NT) — including support for conditional 
compilation.* 

• Port VB projects faster and easier by importing VB forms 
and modules. 

• The debugger supports breakpoints, step over, step in, 
and step out — track down bugs faster and easier. 


• Create Internet-enabled applications using the TCP/IP 
socket tool. 

• Powerful multimedia tools with extensive QuickTime 
support and a Sprite animation engine. 

• Easily localize your applications including double-byte 
character support. 

• Extend functionality with PowerPC Shared Libraries, 
REALbasic native plugins, XCMDs and AppleScript. 

• Single database API with support for Oracle, Microsoft 
SQL Server, 4D Server, Dtf, PostgreSQL, Open Base, or 
any ODBC-compliant database. Includes a single-user 
SQL database engine. 


3 REAL Software, Inc. 


Download a FREE trial version NOW! at www.realbasic.com or call 512.263.1233 for more information 


* Apple Design Awards awarded to REALbasic 1-0. Congratulations Geoff and Jeannie! ** MacWorld rating awarded to REALbasic 2.0.2. 
^Windows compilation and database support require Professional Edition. REALbasic is a trademark of REAL Software, Inc 










Whoa. New technology. 
I need updated tools. 



solves problems. We're continually updating our award-winning 
Mac-hosted development suite so your applications can take advantage of the 
Latest technologies from Apple, Thinking about Mac OS X, Carbon or AltiVec? 

$o is Metro werks. todeWarrior - still fast,, powerful, easy to use. 

No probLem w that, righ t ? _ 


PROBLEM SOLVED. CODEWARRIOR. 

1 . 800 . 377.541 6 

For more information on CodeWarri or ’s support for new Apple technology, check out; 

www.metrowerks.com/newtech 
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